Errores¶

Los códigos y mensajes que devuelve kubelatch, qué significan y qué hacer con cada uno. Los mensajes están en español y se muestran tal cual en kubectl y en la interfaz.

Errores del proxy¶

El proxy (/clusters/<id>/...) responde siempre con un objeto Status de Kubernetes, así que kubectl muestra el mensaje directamente:

{"kind": "Status", "apiVersion": "v1", "status": "Failure", "message": "credencial revocada", "reason": "Unauthorized", "code": 401}

Toda respuesta lleva la cabecera Audit-ID. Si abres una incidencia, incluye ese valor.

Código	Mensaje	Qué significa	Qué hacer
`400`	`ruta no válida: segmentos vacíos, '.' o '..' o caracteres escapados no están permitidos`	La ruta tiene `//`, `.`, `..`, un escape o un `%`.	Revisa el `server` del kubeconfig: debe ser `https://<kubelatch>/clusters/<id>`, sin nada más.
`400`	`identificador de cluster no válido: …`	El segmento tras `/clusters/` no puede ser el id de un cluster.	Usa el kubeconfig que te dio kubelatch.
`400`	`kubelatch no admite cabeceras Impersonate-* (kubectl --as no está soportado)`	Usaste `--as`, `--as-group` o una herramienta que usa la impersonación.	Quita `--as`. Si necesitas probar permisos de otro, usa el acceso nativo de administración.
`401`	`hace falta un token de kubelatch (Authorization: Bearer klt_...)`	No hay token, o no tiene el formato de un token de kubelatch.	Comprueba que el kubeconfig tiene el `token` completo.
`401`	`credencial desconocida`	El token no existe en kubelatch (mal copiado, de otra instalación, o su cluster se borró).	Emite una credencial nueva.
`401`	`credencial revocada`	Alguien revocó la credencial.	Emite una nueva; si no fuiste tú, avisa a un admin.
`401`	`credencial caducada`	Pasó su fecha de caducidad.	Renueva la credencial.
`403`	`la cuenta está deshabilitada`	La cuenta dueña de la credencial está deshabilitada.	Habla con un admin.
`403`	`esta credencial está restringida al cluster <id>`	La credencial se emitió para otro cluster.	Usa el contexto correcto o emite una credencial para este cluster.
`403`	`user:<login> no tiene permisos activos en el cluster <id>`	No tienes ningún permiso vigente en ese cluster (nunca lo tuviste, se revocó o caducó).	Pide el permiso a un admin.
`403`	`la credencial ya no es válida: revocada, caducada, cuenta deshabilitada o permisos cambiados`	La petición estaba en curso y se cortó porque algo cambió.	Vuelve a lanzarla; si sigue fallando, mira las filas anteriores.
`404`	`cluster desconocido`	No hay ningún cluster con ese id.	Revisa el `server` del kubeconfig.
`500`	`error interno`	Fallo inesperado de kubelatch.	Busca el `Audit-ID` en el log de kubelatch.
`502`	`no se pudo hablar con el API server del cluster: tiempo de espera agotado`	El API server no respondió a tiempo.	Un admin debe revisar la red entre kubelatch y el cluster.
`502`	`no se pudo hablar con el API server del cluster: el certificado del API server no coincide con la CA registrada`	El certificado del API server cambió o no es el registrado.	Un admin vuelve a ejecutar el one-liner con el kubeconfig actual del cluster (trae la CA nueva) y pega el JSON en «Volver a pegar tokens».
`502`	`no se pudo hablar con el API server del cluster: API server inalcanzable`	Conexión rechazada, nombre sin resolver o red inalcanzable.	Un admin comprueba la URL del cluster y la ruta de red (ver Clusters privados).
`502`	`no se pudo hablar con el API server del cluster: error de conexión`	Otro fallo de conexión.	El detalle completo está en el log de kubelatch.
`503`	`el cluster todavía no tiene tokens configurados`	El cluster está registrado pero falta pegar el JSON del bootstrap.	Un admin termina el registro del cluster.
`503`	`kubelatch no puede consultar su base de datos`	Postgres no responde, o (si solo pasa en un cluster) sus tokens no se pueden descifrar porque cambió `KUBELATCH_ENCRYPTION_KEY`; el log dice `proxy: load cluster`.	Un admin revisa Postgres o vuelve a pegar los tokens del cluster.
`503`	`kubelatch no puede registrar la petición`	No se pudo escribir la fila de auditoría; sin ella la petición no se reenvía.	Un admin revisa Postgres.
`503`	`kubelatch se está reiniciando`	La réplica se está apagando (un rollout).	Reintenta: kubectl y client-go lo hacen solos.

Un 403 con un mensaje en inglés del estilo User "user:<login>" cannot list resource "secrets"… no es de kubelatch: es el RBAC del cluster diciendo que tu nivel no incluye esa acción (ver Niveles).

Estados que solo verás en la auditoría¶

Estado	Error	Qué significa
`101`		Una conexión actualizada (`exec`, `attach`, `port-forward`, `cp`). La fila se completa al cerrarse.
`101`	`stream cortado: la credencial ya no es válida`	Un stream abierto que kubelatch cortó al revocar, caducar, deshabilitar o cambiar permisos.
`499`	`cliente desconectado`	El cliente colgó antes de recibir la respuesta.
cualquiera	`kubelatch reiniciando`	El stream se cortó porque la réplica se apagaba.

Cuando el login con GitHub falla, kubelatch redirige a /login?error=<código> (o a /mi-cuenta?error=<código> si vinculabas desde «Mi cuenta»), y la página muestra el mensaje de la tabla. Cada código tiene un ancla #github-<código>.

Código	Cuándo ocurre	Mensaje en la interfaz
`state`	Falta la cookie de estado, caducó (10 min), no coincide, o al vincular desde «Mi cuenta» la sesión del navegador no es la de quien empezó.	La sesión de inicio con GitHub ha caducado o no es válida. Vuelve a intentarlo.
`denied`	La persona canceló la autorización en GitHub.	Has cancelado el acceso en GitHub.
`github`	GitHub devolvió otro error, falló el canje del código, la consulta de identidad o de pertenencia, o la de los ajustes de 2FA de la organización.	GitHub no ha respondido como se esperaba. Vuelve a intentarlo en un momento.
`not_member`	La cuenta de GitHub no es miembro activo de la organización (o su invitación está pendiente).	Tu cuenta de GitHub no es miembro activo de la organización.
`no_2fa`	La organización no exige doble factor y `GITHUB_REQUIRE_ORG_2FA` es `true`.	La organización de GitHub no exige doble factor; un administrador de la organización debe activarlo antes de que kubelatch acepte accesos con GitHub.
`unknown_account`	Esa cuenta de GitHub no está vinculada a ninguna cuenta de kubelatch, o se desvinculó durante el login.	Esa cuenta de GitHub no está vinculada a ninguna cuenta de kubelatch. Pide a un administrador un enlace de vinculación.
`disabled`	La cuenta de kubelatch está deshabilitada.	Tu cuenta está deshabilitada.
`link_gone`	El enlace de invitación o vinculación caducó, ya se usó o se revocó.	El enlace ha caducado o ya se ha usado; pide uno nuevo a un administrador.
`github_taken`	Esa cuenta de GitHub ya está vinculada a otra cuenta de kubelatch.	Esa cuenta de GitHub ya está vinculada a otra cuenta de kubelatch.
`already_linked`	Desde «Mi cuenta»: tu cuenta ya está vinculada a otra cuenta de GitHub.	Tu cuenta de kubelatch ya está vinculada a otra cuenta de GitHub. Pide a un administrador que la desvincule primero.
`rate_limited`	Demasiados intentos de login desde la misma IP (10 por minuto, compartidos con el login con contraseña).	Demasiados intentos desde esta dirección. Espera un minuto y vuelve a intentarlo.
`server`	Error interno de kubelatch al completar el acceso.	Error interno al completar el acceso con GitHub. Vuelve a intentarlo.

Un código desconocido muestra «No se pudo entrar con GitHub.». Casi todos los fallos dejan un login.failure con el código en el registro del plano de control; los de state por cookie ausente, caducada o de otra sesión, y los de server, solo quedan en el log. Cómo resolver cada caso está en Si algo falla y en Solución de problemas.

Errores de la API¶

Bajo /api/, los errores son JSON con un solo campo:

{"error": "sesión caducada o no válida"}

Código	Mensajes habituales	Qué significa
`400`	`cuerpo JSON no válido`; el motivo concreto de una validación (`el namespace kube-system está protegido: …`, `ttl no válido: usa por ejemplo 7d o 12h`, …)	Petición mal formada o que no cumple la política.
`401`	`sesión no iniciada`; `sesión caducada o no válida`; `usuario o contraseña incorrectos`	Falta la sesión, caducó o se revocó; o el login falló (el mensaje es el mismo para cualquier motivo).
`403`	`solo para administradores`; `petición de otro origen rechazada`; `esta cuenta entra con GitHub: no usa contraseña`; `solo un administrador puede operar sobre credenciales de otros`; `solo puedes consultar tus propios permisos`	Falta el rol, la petición viene de otro origen o la acción no está permitida a esa cuenta.
`404`	`no encontrado`; `usuario no encontrado`; `cluster no encontrado`; `enlace no válido`; `el acceso con GitHub no está configurado`	El recurso no existe (o no es tuyo).
`405`	`método no permitido`	Ruta conocida, método no admitido. La cabecera `Allow` dice cuáles valen.
`409`	`ese permiso ya existe`; `ese login ya existe (los logins no se reutilizan)`; `no se puede quitar ni deshabilitar al último administrador activo`; `sin permisos activos: no hay ningún cluster al que dar acceso`; `ya hay una reconciliación de este cluster en curso`; `el cluster no tiene tokens todavía: …`	Conflicto con el estado actual.
`410`	`el enlace ha caducado o ya se ha usado; pide uno nuevo a un administrador`	Enlace de invitación o vinculación gastado, caducado o revocado.
`413`	`cuerpo demasiado grande`	Más de 64 KiB.
`429`	`demasiados intentos`	Cuenta bloqueada 15 minutos tras 5 fallos, o límite de 10 intentos por minuto e IP.
`500`	`error interno`	Fallo inesperado; el detalle está en el log.
`502`	Un resumen del fallo del cluster	Listar los namespaces de un cluster, conceder un permiso o reconciliar necesitaba hablar con el cluster y no pudo.
`503`	`el intercambio de CI no está configurado`; `el reconciliador no está disponible`	Una pieza interna no está disponible.

Intercambio de CI¶

POST /v1/ci/github-actions/token usa el mismo formato {"error": "…"}:

Código	Mensaje	Qué hacer
`401`	`token no válido`	Cualquier problema del propio token: firma, caducidad, audiencia, emisor, reutilización. El motivo exacto está en el log y en el evento `ci.exchange.failure`. Comprueba que la audiencia es tu `KUBELATCH_BASE_URL`.
`403`	`ninguna trust rule coincide con este workflow (repository_owner_id=… repository_id=… ref=… environment=…): …`	Un admin debe crear la trust rule con esos ids.
`403`	`el bot <bot> de la trust rule «<regla>» está deshabilitado`	Un admin rehabilita el bot.
`403`	`el bot <bot> no tiene permisos activos en ningún cluster: …`	Un admin concede permisos al bot.
`429`	`demasiados intentos`	Más de 60 peticiones por minuto desde la misma IP.

Un token rechazado por la política (403) no se gasta: el workflow puede reintentar cuando el admin arregle la configuración.

Webhook de GitHub¶

POST /v1/github/webhook responde 404 sin GITHUB_WEBHOOK_SECRET, 401 firma no válida si el secreto no coincide, 415 si el content type no es application/json, 413 con más de 1 MiB y 400 si el cuerpo no es JSON. Un member_removed del último administrador que puede entrar responde 200 pero no deshabilita a nadie: revisa el log.