Error codes

API errors have an HTTP status and a JSON body:

{
  "error": "forbidden",
  "message": "pods is forbidden: User \"alice\" cannot delete resource \"pods\" in the namespace \"prod\"",
  "requestId": "4f1c…"
}

error is a stable code you can branch on. message is for people and can change. requestId matches the server log line for the failure, so include it when you report a problem. detail holds the Kubernetes API server’s own reason when it refused a request (such as cannot unmarshal string into Go struct field DeploymentSpec.spec.replicas of type int32) or where a YAML stops parsing; outside production mode it may add other technical context, and source names the code that answered.

Codes you’ll see most

Code	Status	Means
`unauthorized`	401	The bearer token or proxy headers aren’t valid, or the cluster refused KubeGlass’s credentials
`sign_in_required`	401	In `oidc` and `token` modes: there is no sign-in session, or it ended. The UI goes to the sign-in page
`cookie_conflict`	401	In `oidc` and `token` modes: the browser sent more than one KubeGlass session cookie, as when another site under the domain set one, so KubeGlass believes none of them. Delete the site’s cookies in the browser, then sign in again. A WebSocket refused for this closes with 4401 and the reason `cookie_conflict`
`csrf_failed`	403	A request with a sign-in session that changes something didn’t come from a KubeGlass page: it was cross-site, or it lacked the session’s `X-CSRF-Token`
`token_other_cluster`	403	Signed in with a pasted token (`token` mode), you asked for another cluster than the token’s. The token is only sent to its own cluster
`forbidden`	403	Kubernetes RBAC doesn’t allow this for you. The message is Kubernetes’ own
`admin_required`	403	Only KubeGlass admins may do this (adding clusters, changing settings, audit log, drift). See `admin_users`
`act_as_forbidden`	403	You chose “Act as…” for an identity you aren’t allowed to impersonate
`read_only`	403	KubeGlass runs read-only (`--read-only`), or you marked this cluster read-only and the request carries `X-KubeGlass-Read-Only: 1`. The message says which
`not_found`	404	The resource doesn’t exist, or you can’t see it
`conflict`	409	The resource changed since you loaded it. Reload and apply again
`edit_conflict`	409	An edit from the YAML editor changes a field that also changed on the cluster since the editor loaded it. `fields` names them, `live` is the object now and `rebased` is the object now with the edit’s other changes; send the edit again with `"overwrite": true` to keep your values
`already_exists`	409	A resource with that name exists
`context_mismatch`	409	The request’s `X-KubeGlass-Context` names another cluster than its session is on, as after the session was replaced. `context` names the session’s cluster, and the UI moves the tab there and says so
`bad_request`	400	The request doesn’t make sense as sent
`invalid`	422	The API server refused the object as invalid. The message is its own and names the fields, such as an immutable ConfigMap’s `data` or a TLS Secret without `tls.key`
`rate_limited`	429	Too many requests from this client; retry after the `Retry-After` header
`internal_error`	500	Something failed inside KubeGlass. Check the log for the `requestId`

Input

Code	Status	Means
`invalid_parameter`, `invalid_field`	400	A parameter or field has a value KubeGlass can’t use
`missing_field`, `missing_name`	400	Something required is missing
`invalid_namespace`, `invalid_name`	400	Not a valid Kubernetes name
`invalid_body`, `invalid_request`	400	The body can’t be decoded
`body_too_large`	413	The request body is over the limit (`max_request_body_size`, `max_dynamic_body_size` for a manifest or a YAML apply, or 256 MiB for a file uploaded to a pod)
`empty_yaml`, `no_objects`, `too_many_objects`	400	The YAML holds no objects, or more than 500
`apply_failed`	422	Every object of a manifest failed; `data.results` says why each one did
`manifest_fetch_failed`	400, 502	A manifest URL can’t be fetched: not HTTPS, not a public address, larger than 2 MiB, not YAML or JSON, or the server didn’t answer
`name_mismatch`, `namespace_mismatch`	400	The manifest names a different resource than the URL
`invalid_yaml`	422	The YAML doesn’t parse as one object; `detail` names the line
`edit_changes_identity`	422	An edit changes the object’s `apiVersion`, `kind`, `name` or `namespace`, which an edit can’t do
`unsupported_resource`	400	The action doesn’t work on that resource type

Undoing a change

From POST /api/v1/namespaces/{namespace}/{resource}/{name}/revert:

Code	Status	Means
`already_reverted`	409	The change was already undone
`changed_since`	409	The fields the change set have changed again since, so undoing it would undo the later change too. `paths` lists those fields
`replaced`	409	The object was deleted and created again under the same name since the change, so undoing it would change another object
`not_revertible`	422	KubeGlass can’t undo this change: a Secret’s values, a change too large to keep, one whose copy was dropped, a config write or an older revision read from the cluster’s records, a Helm release’s revision (roll it back with Helm), a change to an object deleted since, an automatic change whose updates removed a field that holds other fields and set it again, or a kind of change it doesn’t undo
`not_found`	404	KubeGlass has no record of that change to this object

Clusters and connections

Code	Status	Means
`api_unreachable`	502	The cluster’s API server didn’t answer
`api_unavailable`	502	The cluster’s API server answered that it can’t handle the request right now (its own 503). Asking again in a moment may work
`request_timeout`	503	The request ran past KubeGlass’s limit for it, so KubeGlass stopped waiting: 30 seconds for most API requests, up to 55 for those that download from a chart repository, check many clusters or apply a manifest, and 15 minutes for file transfers. The UI doesn’t send it again by itself
`timeout`	504	The API server said the request timed out, or listing a folder or reading a file for its preview in the Files view took longer than 20 seconds, as a folder of very many entries on a busy node or a pipe can. The UI doesn’t send it again by itself
`credentials_failed`	502	The kubeconfig’s credential plugin (such as `aws`, `gke-gcloud-auth-plugin` or `kubelogin`) failed, so KubeGlass had no credentials to ask the cluster with. The message ends with the plugin’s error
`context_not_found`	404	No kubeconfig context with that name
`context_switch_failed`	500	Switching to the context failed; the message says why
`invalid_kubeconfig`, `kubeconfig_too_large`	400	The pasted or uploaded kubeconfig can’t be used
`cert_untrusted`	400	Adding a cluster by token: the cluster’s certificate isn’t trusted. Paste its CA certificate, or turn on not checking the server’s certificate
`token_refused`, `token_forbidden`	400	Adding a cluster by token: the cluster refused the token, or took it but it may not read the cluster’s version. Adding a cluster never answers 401 or 403
`invalid_connection`	400	Adding a cluster by token: no client can be made with the settings, as with a CA certificate that isn’t one
`unreachable`, `connect_failed`	502	Adding a cluster by token: nothing answered at the address (the message says what the connection got), or the cluster answered with an error
`discovery_failed`	502	API discovery against the cluster failed
`no_cluster`	503	KubeGlass is in setup mode, waiting for a kubeconfig

Metrics

Code	Status	Means
`metrics_unavailable`	503	No metrics-server or Prometheus to ask
`prometheus_required`	503	This needs Prometheus, not just metrics-server
`prometheus_other_cluster`	503	The session’s cluster has no Prometheus: it isn’t the cluster KubeGlass started on and has no Prometheus URL of its own (Settings › Clusters)
`dependency_unavailable`	404	No Alertmanager for this cluster: none is configured or found, or KubeGlass uses another cluster’s
`invalid_query`	400	Prometheus couldn’t parse the PromQL; the message is Prometheus’s, with where in the query
`query_execution_failed`	422	Prometheus couldn’t run the query, as one that would load too many samples or match many to many; the message is Prometheus’s
`query_timeout`	504	The query took longer than Prometheus or KubeGlass allows; narrow it or pick a shorter range
`metrics_query_failed`, `query_failed`	502	Prometheus didn’t answer, answered with a server error, or didn’t answer the last queries, so KubeGlass waits 30 seconds before asking it again

Helm and terminals

Code	Status	Means
`helm_error`	500	Helm reported an error; the message is Helm’s
`repo_name_taken`	409	Another chart repository has that name, at the URL the message names; add this one under another name, or update that one
`revision_not_found`, `no_rollback_target`	404, 400	The revision to roll back to doesn’t exist
`too_many_helm_operations`	429, 503	You run 16 Helm operations already (429), or all users run 1024 (503); start this one when one has ended
`portforward_limit_reached`	429	Too many port-forwards open
`portforward_timeout`	504	The pod didn’t accept the port-forward in time
`too_many_transfers`	429	Too many file uploads and downloads are running: 6 per user, 32 in all; retry after the `Retry-After` header

POST /auth/token (token mode) answers token_rejected (401) when the cluster doesn’t accept the token, invalid_token (400) when it isn’t one, and cluster_unreachable (502) when KubeGlass couldn’t ask. Failed OIDC sign-ins return to the sign-in page with ?error= set to state, denied, provider, exchange, token, busy or internal; Sign-in explains them.

Other codes are specific to one endpoint (for example range_too_wide for a metrics query or sso_session_limit for sign-in through an identity provider). Their message explains what to change.