Skip to content

Troubleshooting: Native KVM

Agent offline

Symptom: AGENT_OFFLINE. An offline agent is not a dead host. Running guests may still be healthy.

  • Check the agent service on the host.
  • Check the network path from the host to the panel.
  • Do not reboot the host to "fix" an agent outage.

KVM unavailable

Symptom: KVM_UNAVAILABLE. /dev/kvm is not available to the agent.

  • Confirm the CPU exposes VT-x/AMD-V and the KVM module is loaded.
  • Confirm the agent user can access /dev/kvm.
  • Until fixed, the node is not provisioning-ready.

libvirt unavailable

Symptom: LIBVIRT_UNAVAILABLE. Start and enable libvirtd; check socket permissions.

Nested virtualisation

Symptom: NESTED_VIRTUALIZATION_DISABLED. Enable nested virtualisation if the workload requires it; otherwise no action is needed.

Storage and network readiness

Symptom: NO_STORAGE_BACKEND, STORAGE_BACKEND_OFFLINE, NO_NETWORK_PROFILE, NO_IMAGE, NO_IPV4. Each blocks provisioning for a specific reason. Add or repair the named backend/profile/image/pool.

Compute inventory stale

Symptom: COMPUTE_INVENTORY_STALE, CPU_TOPOLOGY_NOT_SYNCED. Use the agent.refresh_capabilities repair, or wait for the next agent report.

Honesty reminder

Live libvirt/QEMU integration is not tested on hardware in this build. Do not treat a green discovery report as proof that provisioning will succeed.