Settings & help

Troubleshooting

Cluster connection issues

”Failed to connect” with a red dot

The kubeconfig context is reachable in name only. Common causes:

The cluster endpoint is unreachable (VPN required, IP allow-list)
TLS certificate has expired or is self-signed with no CA in the config
Exec plugin (gke-gcloud-auth-plugin, aws eks get-token) is missing or failing - check which gke-gcloud-auth-plugin in a fresh terminal
Bearer token has expired

The error message in the sidebar usually tells you which. Hit Retry after fixing.

Exec plugin not found

If your shell PATH includes the plugin but Kubius can’t see it, this is usually because the app was launched from Finder and didn’t inherit your interactive shell’s PATH. Kubius invokes exec plugins via a login shell ($SHELL -l -c …) which loads your .zprofile / .bash_profile - make sure the PATH update lives there, not just in .zshrc / .bashrc.

”Forbidden” errors but cluster is up

You’re connected but RBAC denies listing namespaces. Kubius falls back to a default list (default, kube-system, kube-public) so you can still operate - pick a namespace you do have access to.

Logs

Logs say “Reconnecting…” in orange

Either:

The pod is restarting and the stream is broken - Kubius will reconnect automatically (exponential backoff up to 30s)
One container in a multi-container view is terminated - that container can’t follow logs. Aggregate badge stays green if any other container is actively streaming.

Logs cut off after a few minutes

Kubius’s stream timeout is 360s; the K8s server closes the stream at 300s. Reconnect happens automatically and is invisible - you don’t lose buffered lines.

Port forwarding

”Local port X is already forwarded”

Stop the existing session in the floating Port Forwards tray, then try again. Or let quick-forward pick the next free port (it auto-increments on collision).

Browser refuses to load `localhost:6000`

That’s an unsafe port - see Port Forwarding → Unsafe ports. Pick a port above 1024 that isn’t on the Fetch blocklist.

Terminal

Terminal closes immediately

The container has no shell (/bin/bash, /bin/sh, or sh). This is common with distroless / scratch images. Use a temporary debug pod or rebuild the image with a shell.

Garbled output

Resize the window - the PTY needs a re-init. If that doesn’t help, the container’s TERM env may conflict; try TERM=xterm-256color explicitly.

Performance

Switch from All Namespaces to a specific namespace - drastically reduces the watch volume
Turn off the System toggle if you don’t care about kube-system / GKE-managed namespaces
Close unused floating log windows and terminal sessions

App uses lots of memory

Long-running watches accumulate state. Cluster switching releases everything for the previous cluster. If you have ten windows open across three clusters and metrics history for a thousand pods, memory will be substantial.

Reporting issues

Kubius is in active development. If something’s wrong, please describe:

Which Kubernetes version / cluster type (GKE / EKS / kind / local)
macOS version
What you clicked, what you expected, what happened
Any error message from the cluster (the connection-failed banner, the brand alert dialog, etc.)