Skip to content

Troubleshooting cookbook

Start with facts, not guesses.

General status

incus version
incus info
incus list
incus storage list
incus network list
incus profile list

Instance will not start

incus info app-01
incus start app-01 --debug
incus console app-01 --show-log

Check common causes:

  • storage pool full;
  • bad device in profile;
  • duplicate proxy port;
  • missing network;
  • VM disk too small;
  • invalid raw config.

Cannot exec into a VM

If the VM just booted, wait:

incus exec app-vm -- cloud-init status --wait

If the agent is not ready:

incus console app-vm --show-log
incus restart app-vm

Common causes:

  • VM is still booting;
  • image is not a cloud image, or lacks Incus agent/cloud-init support;
  • cloud-init is stuck or the VM was launched from a non-cloud image;
  • VM has no network;
  • system is overloaded.

No network inside instance

incus config show app-01 --expanded
incus network list
incus exec app-01 -- ip addr
incus exec app-01 -- ip route
incus exec app-01 -- ping -c 3 1.1.1.1
incus exec app-01 -- getent hosts example.com

Likely causes:

  • no NIC device;
  • wrong profile;
  • DHCP disabled;
  • host firewall blocking forwarding;
  • DNS misconfigured;
  • duplicate static lease.

Port forwarding does not work

incus config device show app-01
incus info app-01
ss -ltnp

Check:

  • proxy device listen address;
  • host firewall;
  • app listens inside the instance;
  • port already used on host;
  • connect target uses the right instance-side address and port.

Storage full

incus storage info default
incus list
incus image list
incus storage volume list default

Clean candidates:

  • old stopped instances;
  • old snapshots;
  • unused images;
  • forgotten custom volumes;
  • failed exports.

Cloud-init failed

incus exec app-vm -- cloud-init status --long
incus exec app-vm -- journalctl -u cloud-init --no-pager -n 200
incus exec app-vm -- cat /var/log/cloud-init-output.log

Most failures are YAML indentation, package mirror/network issues, or scripts that assume services are ready too early.

Profile problems

incus profile show default
incus config show app-01 --expanded

If a device comes from a profile, fix the profile or remove that profile from the instance:

incus profile remove app-01 problem-profile

Safe recovery habit

Before attempting repairs:

incus snapshot app-01 before-repair

After repair succeeds:

incus delete app-01/before-repair

If repair fails:

incus restore app-01 before-repair