Troubleshooting

Troubleshooting

Start by re-running sudo bull init: it re-checks every dependency and repairs the libvirt storage pool, NAT network, and plugin if they are missing. Failures are also logged to ${BULL_HOME}/bull-error.log. For verbose output, set BULL_DEBUG=1.

KVM not available

KVM not available. Enable nestedVirtualization in ~/.wslconfig

/dev/kvm is missing. On bare metal, enable VT-x/AMD-V in the BIOS. On WSL2, add to ~/.wslconfig on Windows:

[wsl2]
nestedVirtualization=true

Then wsl --shutdown and reopen. Alternatively, force VirtualBox with export BULL_PROVIDER=virtualbox.

vagrant / vagrant.exe not found

• Native Linux: let bull init install Vagrant, or install it from HashiCorp. On Ubuntu 24.04+ Vagrant left the apt repos; Bull adds the official HashiCorp repo automatically.
• WSL2 + VirtualBox: Vagrant must be installed on Windows, not inside WSL2. Bull then calls vagrant.exe.
• If Vagrant was just installed but is not found, your PATH is stale — open a new shell or source ~/.bashrc.

vagrant-libvirt plugin missing

vagrant-libvirt plugin not installed (run: bull init to install)

Run sudo bull init. If the plugin install fails, ensure the build dependencies are present: libvirt-dev, build-essential, ruby-dev, pkg-config.

Storage pool or network errors (libvirt)

If vagrant up times out waiting for an IP, the default NAT network or storage pool is likely missing or inactive. bull init creates and starts both. To check manually:

sudo virsh pool-list --all
sudo virsh net-list --all
sudo virsh net-start default
sudo virsh pool-start default

UEFI boot fails (OVMF_VARS_4M.fd missing)

Ubuntu's ovmf package ships .ms.fd and .snakeoil.fd but not the plain OVMF_VARS_4M.fd. Bull creates a symlink during init. If UEFI boot still fails, create it manually:

sudo ln -sf /usr/share/OVMF/OVMF_VARS_4M.ms.fd /usr/share/OVMF/OVMF_VARS_4M.fd

WSL2 + VirtualBox: BULL_HOME warning

BULL_HOME is not on the Windows filesystem

VirtualBox on Windows cannot reach the WSL2 ext4 filesystem, so VM files must live on a Windows drive:

export BULL_HOME=/mnt/c/Users/<you>/.bull

The libvirt provider does not have this restriction and is the recommended WSL2 path.

VirtualBox "incomplete installation" (WSL2)

Bull tries to repair VirtualBox services via an elevated cmd (you will see a Windows UAC prompt) and, as a last resort, offers a winget reinstall. If it still fails, open the VirtualBox GUI on Windows once — that initializes the kernel drivers — then re-run Bull.

Disk keeps growing on WSL2

WSL2's .vhdx grows but never shrinks automatically. After destroying VMs, compact it from Windows. See the steps in Installation → Reclaiming disk space on WSL2.

VPN configured but traffic still leaks

• Connect and run curl ifconfig.me — it should show the VPN exit IP.
• Confirm the interface exists: ip a show tun0 (OpenVPN) or ip a show wg0 (WireGuard).
• Remember the kill switch intentionally allows RFC 1918 LAN ranges for management; traffic to private addresses is not forced through the tunnel.

See VPN and Kill Switch for the full rule set.

Toolkit install rejected

Invalid toolkit URL: contains forbidden characters

The URL must start with https://, http://, git://, git@, or ssh://, and must not contain shell metacharacters. This is the injection guard, not a bug. Use a clean Git URL.

Forgot a VM password

sudo bull show-pass <vm-name>

This decrypts the stored credential with the Bull GPG key. If the VM predates GPG encryption, recreate it.

Still stuck?

Open a bug report with your Bull version, provider, host OS, bash version, and steps to reproduce. Attach relevant lines from ${BULL_HOME}/bull-error.log.