Troubleshooting
Lima VM Issues
Section titled “Lima VM Issues””Lima VM not found”
Section titled “”Lima VM not found””Error: Lima VM 'mvm' is not available. Run 'mvmctl setup' or 'mvmctl bootstrap' first.Fix: Run mvmctl bootstrap (macOS) or mvmctl setup (Linux with Lima installed).
”Failed to run command in Lima VM”
Section titled “”Failed to run command in Lima VM””The Lima VM exists but is stopped.
Fix:
limactl start mvm# ormvmctl dev # auto-starts LimaLima VM is stuck
Section titled “Lima VM is stuck”limactl stop mvm --forcelimactl start mvmIf that fails:
mvmctl destroymvmctl bootstrapFirecracker Issues
Section titled “Firecracker Issues””Firecracker socket not responding”
Section titled “”Firecracker socket not responding””The Firecracker process may have crashed. Check the logs:
mvmctl logs <name>mvmctl logs <name> --hypervisor # Firecracker logs“Failed to create TAP device”
Section titled ““Failed to create TAP device””Cause: Insufficient permissions or TAP device name collision.
Fix:
# Check for orphaned TAP devices (inside Lima VM)limactl shell mvm bash -c "ip link show | grep tap"Instance won’t start after sleep
Section titled “Instance won’t start after sleep”Snapshot may be corrupted after a Firecracker version change.
Fix: Delete the snapshot and cold boot:
mvmctl snapshot delete <name>mvmctl run --template <template> --name <name>Build Issues
Section titled “Build Issues”Nix build fails
Section titled “Nix build fails”# Test the flake locally firstmvmctl shellnix build .#default
# Check for errors in the flakenix flake check”Cache miss” rebuilds
Section titled “”Cache miss” rebuilds”If builds are slow despite no code changes, check that flake.lock hasn’t changed. Any change to flake.lock invalidates the cache.
Network Issues
Section titled “Network Issues”MicroVM has no internet
Section titled “MicroVM has no internet”# Inside the Lima VM, check NAT ruleslimactl shell mvm bash -c "sudo iptables -t nat -L"
# Check the TAP device existslimactl shell mvm bash -c "ip link show tap0"Can’t access project files inside microVM
Section titled “Can’t access project files inside microVM”The Firecracker microVM has an isolated filesystem. Use mvmctl shell to access the Lima VM where your home directory is mounted, or pass volumes with --volume.
Performance Issues
Section titled “Performance Issues”Lima VM is slow
Section titled “Lima VM is slow”Adjust resources:
mvmctl destroymvmctl dev --lima-cpus 8 --lima-mem 16Rootfs corrupted
Section titled “Rootfs corrupted”Rebuild without destroying the Lima VM:
mvmctl setup --recreateLogging
Section titled “Logging”RUST_LOG=debug mvmctl <command>RUST_LOG=mvm=trace mvmctl <command>