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 uninstallmvmctl 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 template build <template> --forcemvmctl up --template <template> --name <name>Build Issues
Section titled “Build Issues”Nix build fails
Section titled “Nix build fails”# Test the flake locally firstmvmctl dev 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.
Stale flake.lock
Section titled “Stale flake.lock”error: flake does not provide attribute ...Cause: Your flake.lock references an old nixpkgs or guest-lib version that doesn’t have the expected outputs.
Fix:
nix flake updatemvmctl build --flake .Disk full
Section titled “Disk full”error: No space left on deviceCause: The Nix store or Lima disk is full.
Fix:
# Run garbage collectionnix-collect-garbage -d
# Check Nix store size (mvmctl doctor warns if >20 GiB)mvmctl doctorHash mismatch (fixed-output derivation)
Section titled “Hash mismatch (fixed-output derivation)”error: hash mismatch in fixed-output derivation got: sha256-XXXX...Cause: The npmHash or outputHash in your flake doesn’t match the fetched content (e.g., upstream package changed).
Fix: Update the hash to the value shown after got: in the error message, or use --update-hash:
mvmctl template build my-service --update-hashTemplate not found
Section titled “Template not found”error: Template 'foo' not foundFix: Check available templates:
mvmctl template listTimeout / Connection errors
Section titled “Timeout / Connection errors”error: timed out waiting for ...Cause: Network connectivity issue or a service failed to start within the expected time.
Fix: Check that the Lima VM has internet access and that your service binds to the correct port. Use mvmctl logs <name> to inspect guest output.
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 dev 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 uninstallmvmctl dev up --lima-cpus 8 --lima-mem 16Wrong backend selected
Section titled “Wrong backend selected”Force a specific backend:
mvmctl up --flake . --hypervisor firecrackermvmctl up --flake . --hypervisor apple-containermvmctl up --flake . --hypervisor dockermvmctl up --flake . --hypervisor qemu # microvm.nixmvmctl doctor # check available backendsRootfs 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>