Troubleshooting

Self-tests

Before debugging a specific sandbox, confirm the backend itself works. Each self-test creates a real guest, verifies exec end-to-end, and cleans up:

heyvm test-apple-virt         # macOS, Apple Virtualization.framework
heyvm test-firecracker        # Linux, Firecracker

A passing test-apple-virt proves the entitlement, the image, and SSH all work on your machine — which narrows any remaining failure to a specific sandbox or a specific image.

Where the logs are

macOS

The virtualization entitlement is missing

apple_virt requires the com.apple.security.virtualization entitlement. Check whether the binary carries it:

codesign -d --entitlements - "$(command -v heyvm)"

If it is absent, re-sign with make sign from a source checkout — see Installing From Source.

The storage device attachment is invalid (VZErrorDomain Code=2)

A killed heyvm create can leave a stale VZ storage attachment behind. Restart the long-lived host process (quit and reopen the desktop app, or restart heyvmd) and create the sandbox again.

A sandbox boots but never becomes reachable

If heyvm create --backend apple_virt reports that the guest never came up on the network, check ~/.heyo/sandboxes/<id>/owner.log for the serial console output. A guest that reaches a login prompt but never acquires a DHCP lease is usually an image problem rather than a backend problem — confirm the backend itself is healthy with heyvm test-apple-virt, which uses the default alpine-3.21 image, and try that image directly:

heyvm create --name probe --backend apple_virt --image alpine-3.21

Orphaned container guests on macOS

heyvm rm now stops and deletes the underlying Apple container resource. Older versions did not, so guests could accumulate at the container layer while heyvm list showed a clean state, each still claiming CPU and memory. To clear any left over from before, audit with Apple's CLI directly:

container list -a                    # compare against `heyvm list`
container stop <id> && container delete <id>

Some stopped guests return to running, so re-run container list -a afterwards and repeat if needed.

Linux

Firecracker cannot create TAP networking

Firecracker needs passwordless sudo for ip, iptables, and sysctl. Run sudo -v first to cache credentials, or add a sudoers rule for those binaries.

mke2fs: command not found when building an image

Image builds need e2fsprogs and a working Docker runtime. Install e2fsprogs from your distribution's package manager.

See Prerequisites for the full per-backend requirements list.