If something fails¶

The most common errors when using kubectl, k9s, Lens, Helm or the CI exchange through kubelatch, and what to do about each one.

Every response from the proxy, including errors, carries the Audit-ID header: give it to an administrator (or look at it with kubectl -v=8) if you need them to investigate a specific request.

401 — not authenticated¶

• hace falta un token de kubelatch (a kubelatch token is required): your kubeconfig has no token, or it isn't kubelatch's. Check that you're pointing at the right file (KUBECONFIG or --kubeconfig).
• credencial desconocida (unknown credential): the token doesn't exist in kubelatch (for example, you typed it by hand and made a mistake, or it's from another instance).
• credencial revocada (credential revoked): someone (you or an administrator) revoked it. Issue a new one: Expiry and revocation.
• credencial caducada (credential expired): it passed its expiry date. Credentials don't reactivate; issue another: Get a credential.

403 — no permission¶

• la cuenta está deshabilitada (the account is disabled): an administrator disabled your account (or a bot's). Ask them to reactivate it if appropriate.
• esta credencial está restringida al cluster ... (this credential is restricted to cluster ...): you issued it for a single cluster and are using it against another. Issue one with no cluster restriction, or one for that specific cluster.
• ... no tiene permisos activos en el cluster ... (... has no active permissions on cluster ...): you have no permission currently valid on that cluster (expired or revoked). Ask an administrator for one.
• Forbidden from the cluster itself (without that kubelatch text in front): you have permissions, but your tier doesn't cover that verb, resource or namespace. Check what your tier allows in Permission tiers.

404 — unknown cluster¶

cluster desconocido (unknown cluster) means the cluster id in your kubeconfig (https://<kubelatch>/clusters/<id>) doesn't exist in kubelatch, for example because an administrator deleted it. Check the context name with kubectl config get-contexts.

400 — invalid request¶

• kubelatch no admite cabeceras Impersonate-* (kubectl --as no está soportado) (kubelatch doesn't support Impersonate-* headers (kubectl --as is not supported)): you used --as or --as-group. kubelatch doesn't let you act as another user; you already act as your own. Remove the flag.
• ruta no válida: segmentos vacíos, '.' o '..' o caracteres escapados no están permitidos (invalid path: empty segments, '.' or '..' or escaped characters are not allowed): the request carries something encoded (%XX) or a double slash. Plain kubectl never generates this; check whether you're using curl or another tool with a badly encoded resource name.

502 and 503 — the cluster or kubelatch isn't responding¶

• 502 no se pudo hablar con el API server del cluster (502 could not talk to the cluster's API server): kubelatch can't reach the real cluster. It's not a problem with your credential; tell an administrator.
• 503 el cluster todavía no tiene tokens configurados (503 the cluster doesn't have tokens configured yet): the cluster is registered in kubelatch but an administrator hasn't finished setting it up.
• 503 kubelatch se está reiniciando (503 kubelatch is restarting): kubelatch is in the middle of a deployment. Retry in a few seconds; a watch retries on its own.

GitHub login¶

If you can't sign in with GitHub, the login screen shows a specific message (you're not an active member of the organization, the account isn't linked, the organization doesn't enforce two-factor, the link expired...). The full list, with what to do in each case, is in Errors.

Certificate (x509) when connecting to a cluster or to kubelatch¶

If kubectl answers something like x509: certificate signed by unknown authority or certificate is not trusted:

• Against kubelatch: your kubeconfig doesn't carry the right CA. If kubelatch uses a private CA, an administrator can configure kubelatch so new kubeconfigs already include the CA; in the meantime, add it yourself with kubectl config set-cluster <id> --certificate-authority=<ca.crt> --embed-certs=true.
• kubelatch's kubeconfig never validates the real Kubernetes cluster's certificate: kubelatch does that internally with the CA the administrator registered for that cluster. A certificate error from the cluster itself isn't something you can fix on your end; report it to an administrator (see Private clusters if the cluster uses its own CA).

If none of this fits, give an administrator the Audit-ID from the response (kubectl -v=8 shows it): with it they can find your request in Auditoría (Audit).