Skip to content

Troubleshooting

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

Troubleshooting

Only issues documented in the repository.

First steps

kaironctl doctor (a hint per problem), kaironctl selftest, ./scripts/must-gather.sh, kaironctl sysdump, kaironctl logs, kaironctl events.

Migration stuck in NeedsRecovery

Expected behaviour after an ambiguous commit. Run kaironctl recover NAME to see the diagnosis, cross-check destinationRuntimeFound/destinationRuntimeStatus (a Prepared session phase is not proof the destination did not commit), then choose ConfirmDestinationCommitted, ConfirmDestinationNotCommitted or ForceAbort with a real reason. Alerts: KaironMigrationNeedsRecoveryStuck, KaironMigrationFailureRateHigh. See docs/runbook-migration-failures.md.

403 errors in dashboard Timeline/System/backup actions after upgrading to v0.10.0

CRDs and RBAC were not applied first. Apply deploy/crd.yaml and deploy/rbac.yaml from the tag (Helm applies crds/ only on first install).

Console (VNC/exec) fails after upgrade

kairon-ui and kairon-node must be upgraded together because the console hop is now TLS by default.

Clients cannot reach the dashboard

It serves HTTPS. Use https:// in KAIRON_UI_URL and set KAIRON_UI_CA for a self-signed certificate.

Self-test cannot cache images (AppArmor-confined FluxVM)

--image-cache-dir must be a path the profile allows (the lab's profile permits only /var/lib/kairon-node/image-cache/**); a systemd unit needs it in ReadWritePaths=.

Features needing a newer FluxVM

Agent-session screen and spec.engine need FluxVM newer than 0.4.8.

Other runbooks in docs/: backup/restore, node fence, recovery drill, cert rotation, Velero, VM export.

Clone this wiki locally