Skip to main content

Troubleshooting

Common problems and where to start.

Connection & auth​

"connection refused" / "i/o timeout" on every kube call​

Your cluster API server isn't reachable from your machine.

  • Verify: kubectl get ns on the same kubeconfig.
  • If the API is only reachable from a bastion, enable the SSH tunnel option on the kubeconfig entry. See Connecting to Clusters.

SSH auth fails — "permission denied (publickey)"​

  • Try auth method: SSH Agent (most common working path).
  • Check that ssh-add -l lists a key that the remote accepts.
  • For encrypted keys without an agent, select Key File and provide the passphrase.
  • Don't forget Test Connection in the dialog — tells you exactly where it breaks.

macOS: kubeconfig was picked but now fails with "operation not permitted"​

The sandbox security bookmark has expired. Remove and re-add the kubeconfig via the Kubeconfigs dialog.

SSH remote: "permission denied (needs 'Use sudo')" or sudo is refused​

The kubeconfig can be read only as root (k3s writes /etc/rancher/k3s/k3s.yaml that way by default). Either:

  • Use your own kubeconfig in ~/.kube/config on the remote host. With an empty path it is found first and needs no sudo, or
  • Tick Use sudo and give the remote user passwordless sudo (NOPASSWD in the sudoers). Sudo is never prompted for a password: if the host asks for one, the kubeconfig is read without sudo.

Resources list​

Stays on "Loading resources…" forever​

Usually means API discovery timed out. Check connectivity with kubectl get --raw /openapi/v2 | head. If that works but Kubezilla hangs, grab the logs with RUST_LOG=debug ./KubezillaDesktop and check for repeated errors.

Kind dropdown missing some CRDs​

Kubezilla lists what the API discovery endpoint returns. If a CRD is brand new, give it a few seconds for the cluster's discovery cache to refresh, then switch contexts back and forth to trigger re-discovery.

"forbidden" errors everywhere​

Your kubeconfig credentials don't have RBAC permissions on that namespace or resource. Kubezilla surfaces these as Reason: message banners — the reason tells you exactly which verb/resource was denied. Fix by adjusting the bound Role/RoleBinding.

Shell & logs​

Shell opens, then immediately closes​

The shell command exited. Most likely:

  • The container doesn't have bash, zsh, or sh (distroless images).
  • The pod is CrashLoopBackOff — attach to a different replica, or start a debug pod.

Ctrl+F in Shell doesn't search the terminal​

Correct — Shell reserves Ctrl+F for the running program (so bash's readline search works). Use Ctrl+Shift+F for in-terminal search.

Log window stops updating​

Streaming ended — the pod was replaced or lost its log handle. Close the window and reopen, or press refresh if available. Log window doesn't auto-close so you keep the buffer.

Port forwarding​

Forward stays "Connecting" forever​

The target pod/service is not listening on the remote port. Open the pod's Info → Containers → Ports to verify.

"address already in use"​

The local port is taken. Stop the other process or click Random in the dialog.

Forward works but is slow (via SSH tunnel)​

Each HTTP request opens a new SSH direct-tcpip channel (~300–500ms). Kubezilla parallelizes them, but a slow bastion bottlenecks everything. If possible, run the bastion closer to your cluster region.

PVC & pod mounts​

"mount failed — FUSE not available"​

  • Linux — install fuse3, add your user to the fuse group, re-login. Check ls -la /dev/fuse.
  • macOS — install macFUSE, reboot, and allow the kernel extension in System Settings.
  • Windows — install WinFsp (select "Core" in the installer).

Pod mount fails with "command not found: dd"​

The container image is too minimal — no dd. Browse works partially (listing files, reading via cat) but mount needs dd for parallel writes. Workaround: use a debug container with a fuller image.

Writes to mounted PVC are slow​

Parallel writes default to 12 workers with 4MB chunks — good for most cases. Bottleneck is usually:

  • The pod's dd throughput (tune with bs= in Advanced if available).
  • Network between your machine and the cluster.
  • PVC backend storage class.

Download shows progress then restarts​

Auto-resume triggered after a truncation or WebSocket drop. Kubezilla re-requests only the missing chunks and re-verifies CRC — no manual action needed.

Helm​

"helm: command not found" when installing/upgrading​

Install the helm CLI: helm.sh/docs/intro/install. List / inspect / rollback / diff / uninstall work without it — only install and upgrade need the binary.

"chart not found" on install​

The chart repo isn't added locally. Either:

  • Run helm repo add <name> <url> && helm repo update first.
  • Or use an OCI URL (oci://...) which doesn't need repo config.

Release stuck in "pending-install" status​

A prior Helm attempt got interrupted. Workaround: helm uninstall --no-hooks <release> from CLI, then reinstall.

Graph view​

Graph is empty​

No seeding resources in the current view. Make sure the table has rows first, then toggle graph mode. Or hit Discover.

Too cluttered​

  • Turn off kind families in the legend (tri-state checkboxes).
  • Filter by status (e.g. show only Failed).
  • Switch to Groups layout — separates connected components.

Performance​

UI feels sluggish​

  • Too many watches? Close unused Info windows and cluster windows — each holds watches open.
  • Very large namespaces (>10k resources)? Narrow the namespace filter or use field selectors. The table is virtualized but filtering still processes each row.
  • Graph mode with thousands of nodes — use a smaller seed set.

High memory usage​

  • Logs have long buffers. Close Log windows you're not watching.
  • Disk usage scans hold the scanned tree in memory. Close the Browse window when done.

App itself​

Panic / crash​

A crash report is saved to the config directory. Next launch shows the crash reporter — submit if you can, it helps fix real bugs.

Path:

  • Linux: ~/.config/KubezillaDesktop/crash-*.json
  • macOS: ~/Library/Application Support/KubezillaDesktop/crash-*.json
  • Windows: %LOCALAPPDATA%\KubezillaDesktop\crash-*.json

App won't launch after an update​

The updater may have left a partial binary. Delete KubezillaDesktop.tmp or *.old files from the config directory and re-run the installer.

Everything broken, want to reset​

Delete state.json from the config directory. The app re-discovers kubeconfigs from ~/.kube/ on next launch. Your kube clusters are not touched.

Where to report bugs​

  • Use Dots menu → Feedback — attaches the current state and an optional screenshot.
  • For dev-level debugging, run with RUST_LOG=debug and capture stderr.