Troubleshooting

macOS says the app cannot be opened

Builds are not notarized yet. Install with Homebrew, or see the unidentified-developer prompt.

Cluster connection lost

kdashboard could not reach the API server of the current context. The overlay shows the underlying error.

Check that the same context works in a terminal: kubectl --context <name> get ns.
On a VPN or a bastion? Connect it, then click Retry connection.
Failed to load contexts: ENOENT means there is no kubeconfig where kdashboard looks — ~/.kube/config, or the path in Settings → Kubernetes → Kubeconfig.
Behind an HTTP proxy? Proxies are not supported yet.

My contexts are missing

kdashboard reads a single file and ignores the KUBECONFIG variable. Set the right path in Settings → Kubernetes → Kubeconfig, or import the other files.

Contexts that authenticate through aws, gcloud, az, kubelogin or another exec plugin need that binary on the PATH. kdashboard reads the PATH of your login shell at start-up.

Make sure the plugin’s folder is added in your login profile (~/.zprofile, ~/.zshrc, ~/.bash_profile), not only in a terminal-specific file.
Restart kdashboard after changing it.
If the plugin needs an interactive login (aws sso login, gcloud auth login), run it in a terminal first.

A table says I cannot list a kind

You cannot list <kind> here is a 403 from the API server: your user lacks that permission in this scope. Pick a namespace you have access to, or check what your user is allowed to do in the RBAC explorer.

<Kind> not available in this cluster is a 404: the API or CRD is not installed — VPA and WPA, for example.

A namespace is missing from the picker

The picker lists the namespaces in which you may list pods. If you can read other kinds there but not pods, the namespace is left out. The result is cached for five minutes.

CPU and memory show ”—”

Live usage comes from metrics-server. Check it with kubectl top pods. Right after a pod starts, Waiting for the next scrape… is normal.

No usage history in pod details

Charts over time need a Prometheus. Set one in Settings → Kubernetes → Prometheus and click Test. The URL must be reachable from your machine, without authentication. http://localhost:9090 with a port-forward to the Prometheus service is the quickest way.

The Security view says “none” or “Not scanned”

kdashboard did not find trivy or grype on your PATH. Install one and restart the app — see Image posture. Scan failed on a private image usually means the scanner has no credentials for that registry; hover the row to read its error.

Cost shows “fallback” rates

The provider or instance type of your nodes was not recognised, so default rates apply. That is expected on kind, minikube and bare metal. See where the rates come from.

The agent panel says the CLI is not installed

The claude or codex command must be on the PATH of your login shell — same rule as for auth plugins above. Restart kdashboard after installing it. For Codex, update to 0.100 or newer: npm i -g @openai/codex.

The agent session ended by itself

Session ended: the Kubernetes context changed. — sessions are pinned to the context they started on. Start a new one, or use Resume to continue the conversation.

The node shell or the debug container does not start

Node Shell needs permission to create privileged pods in kube-system. Clusters that enforce the baseline or restricted Pod Security Standard there, or an admission policy that blocks privileged pods, will refuse it.
Debug needs permission to patch pods/ephemeralcontainers.
Both pull busybox:1.36. An air-gapped cluster needs that image in a registry its nodes can reach.

My edit was reverted

Something else manages the resource — Helm, Argo CD, Flux, an operator or an HPA — and put its own value back. Change it at the source. See how changes are applied.

Start from scratch

Quit kdashboard and delete its data folder. Your kubeconfig and your clusters are not affected.

Still stuck?

Search or open an issue, or ask in Discussions. Include your OS, the kdashboard version, and the exact error text. For a security problem, follow the security policy instead of opening a public issue.