Troubleshooting & FAQ

“Pod is not running” error on connect

Symptom: connecting fails immediately with a message like Pod "my-pod" is not running (phase: Completed) — it may have already exited or failed.

Cause: the plugin checks the target pod’s phase before opening the exec session. A pod that has already exited, failed, or hasn’t been scheduled yet cannot be exec’d into — the same restriction kubectl exec has.

Fix: confirm the pod is actually running:

kubectl get pod POD_NAME -n NAMESPACE

If it shows Completed or Error, the pod’s container has already exited (for example, a pod running a one-shot command rather than a long-lived process); if it shows Pending, it hasn’t been scheduled yet. Either way, the plugin can’t attach to it in that state — pick a pod that’s actually Running, or recreate/restart it first.

Connection fails with an authentication error

Symptom: the connection fails with an authentication-related error, even though the same context worked before.

Cause: if your kubeconfig context uses an exec-based auth plugin (EKS, GKE, kubelogin, …), the plugin runs that binary to obtain a token — the same one kubectl itself would run. If your underlying CLI session (e.g. an aws SSO/login session) has expired, that command fails, and so does the connection.

Fix: re-authenticate with your cluster’s identity provider (for example, re-run aws login / re-authenticate your AWS SSO session), then retry the connection. See Prerequisites for details on how exec-based auth is handled.

Confirming the plugin actually loaded

Symptom: the “Kubernetes Exec” tab type doesn’t appear, or connections behave unexpectedly, and you’re not sure whether the plugin is even loaded.

Fix: open View → Toggle Developer Tools in Tabby and check the console for:

[tabby-k8s-exec] module loaded

If this line is missing, the plugin failed to load — check that it was installed into the correct plugin directory for your OS (see Installation) and that Tabby was fully restarted afterwards.

The terminal disconnects after a few minutes idle

Symptom: a session that’s been left idle for a while (roughly 5 minutes or more) disconnects on its own.

Cause: this is a known limitation of the underlying Kubernetes exec protocol / client library, not something specific to this plugin — some proxies and load balancers in front of the API server close idle exec connections after a timeout, and there is currently no keepalive implemented around it.

Fix: reconnect via Tabby’s reconnect hotkey or by reopening the tab.

/bin/bash session ends immediately

Symptom: connecting with Command set to /bin/bash ends the session right away, before you’ve typed anything.

Cause: the container image doesn’t have bash installed (common with minimal images like busybox or alpine without extra packages).

Fix: if Shell fallback is enabled (the default), the plugin detects this and automatically retries with /bin/sh — you should see a status line announcing the fallback. If it’s disabled, either enable it or set Command to /bin/sh directly.

The plugin doesn’t update after git pull

Symptom: you pulled the latest source changes, but Tabby still behaves like the old version.

Cause: installing from source requires an explicit rebuild and redeploy step — pulling new source alone does not update the files Tabby actually loads.

Fix: run the full update sequence from Installation:

git pull
npm run build
npm run install-plugin

Then fully restart Tabby (not just reload the window).