Skip to content

Troubleshooting

Susant Sahani edited this page Oct 18, 2026 · 1 revision

Troubleshooting

Start with krytonctl doctor (or GET /api/v1/doctor): it checks auth mode, projects, catalog, provider health, and for kubevirt namespaces, DataSources, snapshot CRDs and StorageClass/VolumeSnapshotClass pairing.

Symptom Fix (from repo docs)
Login page asks for a token Auth is apikey and auto-auth is off: read ~/.kryton/lab.token and paste
401 from API/CLI KRYTON_TOKEN must be the raw token, not the hash
parse api keys file: cannot unmarshal array Use the {"keys":[...]} wrapper
Auto-auth does nothing Needs KRYTON_LAB_AUTO_AUTH=true, KRYTON_ALLOW_INSECURE=true, KRYTON_AUTH_MODE=apikey, KRYTON_LAB_TOKEN_FILE
Console iframe shows 401 Ticket expired or krytond restarted; reopen the console
Lost the raw token KRYTON_ROTATE_KEYS=true ./scripts/ensure-api-keys.sh (old token stops working after restart)
Missing DataSources in doctor Run bootstrap-kubevirt-images.sh
KubeVirt VM stuck Provisioning kubectl get vm,vmi,dv in the namespace; check the CDI import
kubernetes config error on start Set KRYTON_KUBECONFIG or KRYTON_KUBERNETES_ENDPOINT
Linux VM never reports an IP, cloud-init hangs on apt/dnf Guest DNS failing. With Cilium kube-proxy replacement set bpf-lb-sock-hostns-only: true in cilium-config and restart agents
Root disk slightly smaller than requested Filesystem-mode PVC overhead; request more or use Block mode
Snapshots fail StorageClass needs VolumeSnapshot support (docs/STORAGE.md); do not snapshot on rancher.io/local-path
Rocky/Alma/CentOS 10 guest fails on old hosts These images need x86-64-v3 (AVX2) in the guest CPU
Lab host hung ./scripts/lab-recover.sh, then restart services

Clone this wiki locally