Skip to main content
Lumovi tries to say what went wrong in plain words, and what to try next. On the start screen, each cluster that can’t be opened gets a short label; hover it to read the full message. Inside a cluster, an error screen has a title, a hint and Try again.
Lumovi showing a cluster it can't reach, with a hint to check the API server, VPN or tunnel, and a Try again button.Lumovi showing a cluster it can't reach, with a hint to check the API server, VPN or tunnel, and a Try again button.

A cluster that doesn't answer, and what to try.

​
Connecting to a cluster

Lumovi couldn’t open a connection to the API server.
  • Check that the cluster is running, and that this computer can reach it. Many clusters are only reachable over a VPN or a tunnel.
  • If you have kubectl, kubectl --context <name> get --raw /version tells you whether the API server answers from this computer.
  • Choose Try again, or Reload on the start screen, once the network is back.
The API server accepted the connection, but didn’t answer within 20 seconds. That’s usually a busy or distant API server.Try again in a moment. If it’s always slow, give it longer with LUMOVI_REQUEST_TIMEOUT_MS. On macOS, quit Lumovi, then:
The certificate authority in your kubeconfig doesn’t match the API server’s certificate. The full message starts with TLS handshake failed.This happens when a cluster is recreated or its certificates rotate. Get a fresh kubeconfig entry from wherever the cluster came from, for example aws eks update-kubeconfig, gcloud container clusters get-credentials or az aks get-credentials, then choose Reload.
The cluster’s address starts with http://, for example through kubectl proxy. Lumovi only uses unencrypted connections when the kubeconfig says so for that cluster, the same rule as the official JavaScript client:
~/.kube/config
The context gets its credentials from a plugin, like gke-gcloud-auth-plugin, aws eks get-token or kubelogin, and the plugin failed.
  • The credential plugin “…” wasn’t found. Install the plugin, or make sure it’s on your PATH. On macOS and Linux, Lumovi reads PATH from your login shell when it starts, even when you open it from the Dock or a launcher. So the plugin must be on the PATH your shell profile sets up. Restart Lumovi after changing it.
  • Could not get credentials: … The plugin ran but failed, most often because you’re signed out of your cloud provider. Sign in again (gcloud auth login, aws sso login, az login…), then choose Try again.
The API server turned down the token or client certificate. Expired credentials end up here. Sign in again, or get a fresh kubeconfig entry, then try again.
Your account isn’t allowed to read this. If you only have access to some namespaces, pick one from the namespace menu. If your account can’t list namespaces, type the name of one you can use. See Namespaces and Permissions.
  • Your kubeconfig couldn’t be read. A file has a syntax error. Lumovi names the file and the first line of the problem. Fix the file, then choose Reload.
  • No clusters found. Lumovi found no contexts. Set KUBECONFIG, or create ~/.kube/config, then reload. See Connecting clusters.
kubectl in your terminal uses the KUBECONFIG your shell profile exports. Lumovi opened from the Dock, Spotlight or a launcher doesn’t see that variable (it takes only PATH from your shell), so it reads ~/.kube/config. Loaded from, at the bottom of the start screen, shows which files it read.Start Lumovi from your terminal, or set KUBECONFIG where apps see it. See Setting environment variables.

​
While you work

Can’t reach … Checking again every 15 seconds. The connection dropped. The last data stays on screen, and Lumovi reconnects by itself when it can. Choose Retry now to check at once, or All clusters to open another.Couldn’t refresh — showing the last data. A refresh failed, but what you see is still the latest Lumovi has. Choose Retry.
Lists load in chunks of 500 and stop at 5,000 objects, so huge clusters stay fast. A note says Showing the first … of …. Choose Filter by label to narrow the list on the server, pick a namespace, or raise the limit with LUMOVI_MAX_LIST_ITEMS.On the Workloads page and add-on pages, the note says Some lists are too long to load whole, and a kind that can’t be listed at all says Couldn’t list … above the rest.
Lumovi asks the cluster what you’re allowed to do before offering an action, and says why it can’t:
  • Your account can’t … in …. Your RBAC doesn’t allow it. See Permissions.
  • Changes are turned off for this cluster. You, or LUMOVI_READ_ONLY, made it read-only. See Read-only mode.
Someone else changed the object while you were editing its YAML. Lumovi doesn’t overwrite their change. Choose Start over from the latest, and make your edit again. See Edit YAML.
Images built without a shell (distroless ones, say) can’t run one. Choose Debug to add a debug container with tools to the pod instead. See Shells and debug containers.Shells are off means the cluster is read-only in Lumovi: shells count as changes.
Port … on this computer can’t be used (EADDRINUSE). Something else on your computer listens on that port. Pick another local port. See Port forwarding.
The object refers to something that isn’t there: a ConfigMap or Secret it mounts, the service account it runs as, an ingress’s backend service, or the node a pod is on. The card is dashed, and can’t be opened. Create what’s missing, or fix the reference.A card without a status is different: Lumovi couldn’t list that kind, usually because your account can’t, so it doesn’t know whether the object exists. See Map.
Lumovi didn’t expect this. Choose Try again first. When a page itself fails, its screen says Lumovi ran into an unexpected problem. Your clusters were not changed., with Reload, Back to clusters, Copy details, and Report issue, which opens a GitHub issue with the error filled in. A detail panel that fails says This object couldn’t be displayed (or This release couldn’t be displayed) the same way, and the list next to it keeps working.
An address Lumovi doesn’t know, like an old link, says This page doesn’t exist, with Go to the overview, or Back to clusters outside a cluster. For a custom kind, a page saying the cluster doesn’t serve it means the cluster doesn’t have that kind: Its CustomResourceDefinition may have been removed, or never installed in this cluster.

​
Usage and metrics

Live usage comes from metrics-server, as for kubectl top. Without it, the overview says Live usage needs metrics-server, and Lumovi shows requests and limits against capacity instead. Install metrics-server in the cluster to see live usage. See Live usage.
History comes from a Prometheus or VictoriaMetrics in the cluster.
  • No Prometheus found. None of the cluster’s services looks like Prometheus or VictoriaMetrics. If yours runs under another name, choose Choose a service to pick its namespace, service, port and path (/select/0/prometheus for vmselect). Look again searches again, after you install one, say.
  • Can’t read usage history. There’s a source, or something that looked like one, but reading it failed. The message under it says why:
    • Your account can’t list services, so Lumovi can’t look for Prometheus. Choose its service yourself, or ask for list on services.
    • Your account can’t reach … through the API server (it needs get on services/proxy). Lumovi reaches the source through the API server with your credentials, so you need get on services/proxy in its namespace.
    • … didn’t answer PromQL or It answered, but not like Prometheus. The service, port or path isn’t a PromQL endpoint. Choose the right one.
  • Usage history is off. It was turned off for this cluster. Choose Change to turn it back on.
See Usage history.
Right-sizing needs usage history, and enough of it. A workload’s note says what’s missing:
  • Too new: it has less than a day of history. Recommendations need a day, and grow more confident up to a week.
  • No usage: Prometheus has no CPU and memory samples for its containers in the last week, or it had no pods.
  • Autoscaled: a VerticalPodAutoscaler sets its requests, so Lumovi leaves it to it.
If Prometheus couldn’t answer for some namespaces, an alert names them, with Try again: the other namespaces still get their recommendations. A namespace that keeps failing usually asks more of Prometheus than its query limits or timeout allow.If Apply… is grayed out, your account can’t change the workload, or the cluster is read-only. If the dialog says the API server refused the change, a quota, a LimitRange or an admission webhook turned it down: untick the change it refuses, or fix the cause first. See Right-sizing.

​
Helm

Looking at releases needs nothing, but changing them runs your own helm. Install Helm, or set LUMOVI_HELM to where it is. On macOS and Linux, helm must be on your login shell’s PATH.
The error shown is what helm said. A failed upgrade is often a chart or values problem, which the dry run usually catches first.If the release is managed by Flux, Lumovi says so and links to its HelmRelease. Flux puts back changes made any other way, so make the change in Flux instead.

​
Installing

The Windows installer isn’t code-signed yet. Choose More info, then Run anyway. You can check the download against the release’s checksums first.
Make the file executable first: chmod +x Lumovi-*.AppImage. Then run it from a terminal to see any error it prints.

​
In your cluster

Each page keeps a WebSocket open to Lumovi, and Reconnecting to Lumovi… shows while it’s down. If it drops every minute or so, something in front of Lumovi closes idle connections. Give your ingress a long timeout, for example with ingress-nginx:
values.yaml
Lumovi also checks each connection every 30 seconds (LUMOVI_HEARTBEAT_SECONDS). Keep that shorter than the idle timeouts of the proxies in between. See Address and ingress.
Sessions live in Lumovi’s memory, so restarting it, as an upgrade does, signs everyone out. With single sign-on, signing in again is a click. Sessions also end after 12 hours, unless you set it otherwise. See Upgrading.
The token is wrong, expired or revoked. Create a new one, for example kubectl create token NAME --namespace NAMESPACE. Lumovi asks the cluster who a token belongs to with a SelfSubjectReview, which needs Kubernetes 1.28 or later. See Tokens.
The token you signed in with expired, or the cluster stopped accepting it. Sign in again to carry on where you were. With single sign-on, Lumovi renews tokens by itself when the provider gives it a refresh token.

​
Reporting a problem

If none of this helps, please open an issue. In the desktop app, Help → Report an Issue… opens the same page. It helps to include:
  • your Lumovi version, shown at the bottom of the sidebar,
  • your operating system, and how the cluster is run (EKS, GKE, kind…),
  • what you did, what you expected, and what happened instead,
  • the details from the error screen, which Copy details copies.
For security problems, please don’t open an issue: see Reporting a vulnerability.