Troubleshooting

Troubleshooting

Find your problem below. If it is not here, open an issue with your system, the Sextant version and what you saw. In About Sextant (the tray icon's menu, or the end of Settings), Copy version info puts the version, the install kind, the operating system, the web view and Tauri versions on the clipboard; paste it into the issue (see About Sextant).

Clusters

"No clusters found" or a cluster is missing. Sextant reads KUBECONFIG (every file in it) or ~/.kube/config, plus files you add. The welcome screen lists the paths it checked. If you set KUBECONFIG in a shell profile, a program started from a launcher or the Dock may not see it: start Sextant from a terminal, or add the file with + → Add kubeconfig file. After editing a kubeconfig, press Refresh kubeconfig (the circular arrows in the cluster rail). A file that cannot be parsed is flagged next to its source and in Settings → Kubeconfig; the clusters from the other files keep working.

"Cannot connect to ". The message below it says why. The usual causes:

Message	What it means and what to do
The cluster cannot be reached	The server is down, the address is wrong, or you are not on the VPN. Check that kubectl --kubeconfig <file> get nodes works from a terminal. Sextant waits about 10 s for a connection before it gives up.
The cluster did not accept the credentials (401)	Expired token or certificate. Log in again with your usual tool (for example your cloud CLI) and press Reconnect.
The authentication plugin from the kubeconfig is missing or failed	The kubeconfig runs a helper program (aws, gke-gcloud-auth-plugin, kubelogin...) that Sextant could not start. A program started from a launcher may have a shorter PATH than your terminal; start Sextant from a terminal, or give the plugin's full path in the kubeconfig.
The server certificate was not accepted	The cluster's certificate authority is missing from the kubeconfig or does not match the server.
You don't have permission to do this (403)	You are connected, but your account may not do that. See the next point.

A table says "No permission in…" or "You don't have permission to list…". Your account may read only some namespaces, or not that kind. Sextant shows what it can and names the namespaces it cannot read. Pick the namespaces you may read in the namespace selector, or ask the cluster administrator for access.

"The cluster does not serve ". The cluster does not have that API (an older cluster, or the CRD is not installed).

A new CRD (Flux, Argo CD, an operator) does not appear. It should appear within a second or two without reconnecting. If it does not, Reconnect the cluster.

The cluster is reachable only through a proxy. Put the proxy in the kubeconfig's cluster entry, as for kubectl:

clusters:
  - name: prod
    cluster:
      server: https://10.0.0.1:6443
      proxy-url: socks5://127.0.0.1:1080   # or http://proxy.corp:3128, https://proxy.corp:3129

http:// and https:// proxies (with user:password@ in the URL if they need a login) and socks5:// proxies work. With socks5:// the proxy resolves the cluster's host name, as socks5h:// does in kubectl — write socks5://: Sextant does not accept the socks5h:// spelling. A cluster entry without proxy-url uses the HTTPS_PROXY (or https_proxy) environment variable Sextant was started with; NO_PROXY is not used. An SSH tunnel opened with ssh -D 1080 bastion is a SOCKS5 proxy on 127.0.0.1:1080. The proxy is used for everything of that cluster: tables, logs, shells and port forwards.

Everything is slow, or the first load takes long. On a big cluster (hundreds of CRDs, thousands of pods) the first discovery takes time; the built-in kinds open without waiting for it. A line "The cluster is slow to respond" with a seconds counter means the API server is answering slowly. Sextant retries 429, 503 and 504 answers a few times by itself. Narrowing the namespace selector makes tables lighter, and label or field terms in the search box (app=web, status.phase=Pending) are applied by the API server. A table keeps at most 20 000 objects and asks before listing more than 10 000 in all namespaces; see Large clusters.

Cloud clusters

"aws is not installed" (or gcloud, az) in the From cloud tab. Sextant looks for the tool in the PATH of the program itself, which for a program started from a launcher or the Dock can be shorter than your terminal's. Install the tool (Installation guide links to the vendor's page) or start Sextant from a terminal. A tool installed while Sextant is running is found the next time you open the tab or press Find clusters.

"… is not signed in, or the sign-in expired", with a command. Sextant does not sign in for you. Run the command shown (Copy command, or Open terminal, which opens a local terminal tab in the dock with the command typed and waits for you to press Enter): aws sso login --profile <profile> (aws configure --profile <profile> for a profile with access keys), gcloud auth login or az login. Then press Find clusters again. The same command and buttons appear under "Cannot connect to " when an already added cloud cluster fails with "The cluster did not accept the credentials (401)" or "The authentication plugin from the kubeconfig is missing or failed" because its sign-in expired; after signing in, press Reconnect. An SSO session usually lasts a few hours, so expect this after a night.

"The sign-in plugin for gcloud is not installed" (or for az). GKE needs gke-gcloud-auth-plugin and AKS needs kubelogin; the tab shows the command to install them (gcloud components install gke-gcloud-auth-plugin, az aks install-cli). You can add the clusters without the plugin, but connecting fails with "The authentication plugin from the kubeconfig is missing or failed" until it is installed and is in the PATH Sextant sees.

An EKS search finds nothing. EKS clusters are searched per region. Tick the regions the clusters live in (only the profile's own region is preselected), and check that the profile may call eks:ListClusters and eks:DescribeCluster.

An AKS cluster is found but will not connect. Sextant signs in to AKS with the token of az login, which works only for clusters with Microsoft Entra ID integration. Also make sure the account you are signed in with has access to the cluster (an Azure Kubernetes Service RBAC role, or a Kubernetes role binding for your Entra ID user or group).

The cloud tool says something else. Other errors of the tools are shown as they are ("aws failed", with the tool's own words). A tool that does not answer within 60 seconds is stopped; check your network and try again.

Metrics

CPU and memory show n/a, or "Metrics are unavailable". There is no source. Current values come from metrics-server (install it in the cluster) or from Prometheus. Open the cluster's settings → Metrics to see what Sextant found, and set the Prometheus address by hand if yours is not found automatically.

There are no charts. The last-hour charts need Prometheus. If it is in the cluster, Sextant looks for it automatically; otherwise set Manual address in the cluster's Metrics settings.

Helm

"Helm is not installed". You can view releases without Helm, but installing, upgrading, rolling back and uninstalling need the helm program. Install it (guide) and come back to the window, or choose the binary in Settings → Helm. If Sextant says the chosen file "is not a working helm binary", point it at the real helm executable.

A release says "unreadable". The stored data of that revision cannot be decoded. Sextant shows the latest revision it can read.

Shells, logs and port forwarding

The shell says it failed. Sextant tries bash and then sh in the container. A minimal image (distroless, scratch) has neither; use a debug container or kubectl debug. For a shell on a node, see the next point.

The node shell does not start. The message under the tab says why:

Message	What it means and what to do
You need permission to create privileged pods in kube-system	Your account may not create pods there. Ask the administrator, or use a kubeconfig that may.
Pod Security admission does not allow privileged pods in kube-system	The kube-system namespace enforces the baseline or restricted Pod Security level, and a node shell is a privileged pod. The administrator has to allow it (label the namespace with pod-security.kubernetes.io/enforce=privileged, or use an exemption); Sextant does not change the cluster for you.
The node shell pod could not start / did not start on node … in 60 seconds:	The reason comes from the pod's events. Typical ones: the image cannot be pulled (a registry that is not reachable from the node, or a wrong name in Settings → Terminal → Node shell image), no room on the node, or the image has no nsenter. Sextant deletes the pod.

Admission policies of your own (Kyverno, Gatekeeper) may also refuse a privileged pod; their message is shown. If the cluster has no access to Docker Hub, set the node shell image to one in your registry (see Settings).

A node shell pod is left in kube-system. Sextant deletes it when the tab, the cluster or the application closes, and cleans up leftovers (yours from earlier runs, and anyone's older than 8 hours) when a cluster connects. If one stays, look for pods with sextant.dev/node-shell=true: kubectl -n kube-system get pods -l sextant.dev/node-shell=true. They end by themselves after 8 hours and are safe to delete.

The local terminal uses the wrong cluster. The shell's startup files may export their own KUBECONFIG, which wins. Run kubectl config current-context before changing anything.

"Local port … is already in use". Choose Use a free port in the port-forward dialog.

Logs stop. A stream ends when the container ends. Press Reconnect in the log tab, or tick Previous container to see the log before a restart.

A merged logs tab says containers wait. At most 20 log streams run at once in one tab. Untick pods or containers in the tab's list to choose which ones are read.

A debug container does not start. "You need permission to update pods/ephemeralcontainers…": ask for that permission, or choose A copy of the pod (it needs permission to create pods). "This cluster does not support ephemeral containers": Kubernetes 1.25 or newer is needed; use a copy. "Pod Security admission refused the debug container": the namespace's Pod Security level does not admit it. An image that cannot be pulled (a registry the nodes cannot reach) shows the reason from the pod; choose an image from your own registry. A container that is still not running after 2 minutes is reported as a timeout.

A pod named …-debug-… is left in a namespace. It is a debug copy left by a Sextant that crashed or could not reach the cluster when the tab closed. It ends by itself within 8 hours, and the next debug copy you start in that namespace deletes it. List them with kubectl get pods -A -l sextant.dev/debug-copy=true; they are safe to delete.

Files says the container has no tar. Sextant copies files with tar in the container, like kubectl cp. Distroless images have none: start a debug copy or use an image that has tar.

A download stopped, and there is a .sextant-download-….part file. Normally a cancelled or failed download removes it; one can stay only if Sextant was killed during the download. It is safe to delete.

Updates and installers

macOS says the app "is damaged". Run xattr -dr com.apple.quarantine /Applications/Sextant.app. See Installation.

Windows shows "Windows protected your PC". Choose More info → Run anyway. See Installation.

"Updates are turned off in this build". A build without the project's update key does not update itself. Download new versions from the releases page.

An update cannot be installed. A .deb is updated with your package manager; a copy that is not an installed package cannot replace itself. Sextant says which one applies. "Could not reach GitHub" is a network or proxy problem.

The tray and the window

"Closing the window keeps Sextant in the tray" is disabled and says no system tray was found. Sextant could not create a tray icon, or on Linux no StatusNotifier/AppIndicator host is running. GNOME needs the "AppIndicator and KStatusNotifierItem Support" extension; Sextant also needs the libayatana-appindicator library (Debian and Ubuntu: libayatana-appindicator3-1). Until then closing the window quits Sextant, so nothing is hidden where you cannot bring it back. Reopen Settings after enabling the extension, and restart Sextant if it still says so. See Settings.

The window is gone and I cannot find Sextant. It is in the tray (the menu bar on macOS): use Show Sextant in the icon's menu, or click the Dock icon on macOS, or on Windows click the icon. Quit Sextant in the same menu really quits it. To stop it hiding, turn off Settings → Window.

Notifications

I get too many notifications, or do not want them. Turn them off in Settings → General → Notifications: all of them, one kind of problem, one cluster, or Mute for 1 hour. See Problems and notifications.

No notifications appear. Check that the switch in Settings → General → Notifications is on, that the category and the cluster are ticked and that nothing is muted; that the cluster is connected (only connected clusters are watched); and that the problem began after the cluster connected (problems already there are not told). Then check your system: notifications for Sextant allowed, do-not-disturb off, and on Linux a running notification service. The Recent notifications list on the Problems page shows what Sextant tried to show.

Installing Flux or Argo CD

The install dialog's problems (the list of versions, a refused download, a failed object, controllers that are not ready, a partial install) are covered on Installing Flux and Argo CD; the manual steps to remove them are there too.

Settings

A banner says the settings file was damaged. Sextant started with defaults and copied the old file to settings.json.bak-… next to it. Copy back what you need from it. See Settings.

"Changes are not saved". The settings file cannot be written. Fix its permissions and restart Sextant.

Argo CD

The diff asks me to sign in. Sextant tried your saved login, argocd-initial-admin-secret and API tokens in Secrets labelled app.kubernetes.io/part-of=argocd. Enter a user and password, or an API token. Single sign-on is not supported; use a token. Remember on this computer saves the login in your system keychain.

"Several namespaces of this cluster look like an Argo CD installation…". Sextant refuses to guess, because connecting to a look-alike could expose your password. Ask the administrator to check the Argo CD installation (a cluster-wide Argo CD is recognized by the ClusterRoleBinding of argocd-application-controller or argocd-server).

"Argo CD is not reachable". The argocd-server pod is not ready or does not answer.

AI agents (MCP)

Problems with the port, the token, Claude Desktop or refused calls are covered on the MCP server page.