Solución de problemas

Aquí están los modos de fallo que es más probable que encuentres, y cómo superar cada uno.

Endpoint atascado en Pending

Síntoma: un endpoint permanece en Pending durante más de unos segundos en la creación. La consola no muestra ningún error; la CLI muestra el mismo estado.

Causa probable: el pod de cómputo no puede programarse. Las razones más comunes son la presión del clúster (ningún nodo tiene la CPU o memoria solicitada libre) o una credencial de extracción de imagen obsoleta. Ambos son problemas del lado del operador.

Qué hacer:

1. Espera 60 segundos. La presión transitoria normalmente se resuelve una vez que otro endpoint se suspende.
2. Si no se resuelve, elimina el endpoint y recréalo. El plano de control reintentará la programación en un nodo diferente.
3. Si la recreación también aterriza en Pending, el clúster no está bien. Presenta un informe en el rastreador de GitHub con el id del endpoint y la hora de reloj.

FATAL: endpoint unavailable en la primera conexión

Síntoma: psql devuelve FATAL: endpoint unavailable en la primerísima conexión a un endpoint recién creado, o tras una larga inactividad.

Causa probable: carrera de arranque en frío. El estado del endpoint es Stopped, tu paquete lo activó, pero Postgres aún está reproduciendo WAL hasta el HEAD de la rama cuando tu cliente se rinde.

Qué hacer: reintenta la conexión. El arranque en frío típicamente se completa en 300–500 ms, pero la primerísima activación de un proyecto recién creado, o tras una inactividad de 24h+, puede tardar de 10 a 30 segundos mientras la caché de páginas del pageserver se calienta. La mayoría de los controladores toleran esto si permites al menos un reintento; el psql en bruto no reintenta por defecto.

# psql with one explicit retry
for i in 1 2; do psql "$URI" -c '\q' && break; sleep 5; done

Si el endpoint sigue no disponible después de 30 segundos, el pod en sí puede haber fallado — comprueba el estado en la consola y consulta la guía de Pending anterior.

Conexión rechazada / con timeout desde una nueva IP

Síntoma: un cliente que se conectaba bien antes es rechazado o tiene timeout tras moverse a una nueva red, o un host recién aprovisionado no puede alcanzar el proyecto en absoluto.

Causa probable: el proyecto tiene una lista de permitidos de IP y la dirección del nuevo cliente está fuera de todo CIDR listado. Las fuentes no listadas se rechazan en el proxy, y el bloqueo cubre la ruta de activación.

Qué hacer: añade el CIDR del cliente (keon ip-allow add <cidr>) o borra la lista, luego permite ~30 segundos para que el cambio se propague al proxy.

keon connection-string devuelve branch_not_found

Síntoma:

$ keon connection-string my-feature --project prj_abc...
Error: branch_not_found: my-feature

…pero la rama existe en la consola.

Causa probable: el nombre no coincide con una rama en el proyecto que apuntaste — normalmente un error tipográfico, o el --project incorrecto. La CLI resuelve una rama por id o por nombre, ya sea que la pases como argumento posicional o mediante --branch, así que un nombre que sí existe se resolverá de cualquier manera.

Qué hacer: confirma el nombre de la rama y el proyecto:

keon branches list --project prj_abc...
keon connection-string my-feature --project prj_abc...

El inicio de sesión devuelve access_denied

Síntoma: el OAuth de Google o GitHub se completa, pero la consola redirige a una página de error citando access_denied.

Causa probable: el inicio de sesión puede estar restringido por una lista de permitidos de correo mientras hacemos el onboarding de nuevas cuentas. Si tu dirección no ha sido habilitada, el callback de inicio de sesión la rechaza.

Qué hacer: contacta a tu operador para que tu dirección sea habilitada. Una vez que se añade a la lista de permitidos, el inicio de sesión se completa normalmente en el siguiente intento.

La sesión de la consola expira a mitad de sesión

Síntoma: la consola funciona durante un rato, luego de repente devuelve 401s en cada llamada de API hasta que cierras sesión y vuelves a entrar.

Causa probable: el JWT firmado por cp expiró y su ventana de renovación ha transcurrido. La consola acuña un JWT de corta duración (≈15 minutos) y, mientras estás activo, lo renueva en segundo plano contra /v1/auth/refresh. La ventana de renovación es fija en 12 horas desde el inicio de sesión: una sesión activa se renueva indefinidamente, pero una pestaña dejada sin tocar más allá de esa ventana ya no puede renovarse.

Qué hacer: cierra sesión y vuelve a entrar. Para automatización headless o de larga ejecución, usa una clave de API nsk_ en lugar de una sesión de navegador — las claves de API no expiran y se revocan explícitamente. Consulta Autenticación.

Dónde presentar errores

Para cualquier cosa no cubierta aquí:

• Errores de producto y solicitudes de funciones: el rastreador de GitHub.
• Vulnerabilidades de seguridad: Seguridad — nunca en el rastreador público.

Pasos de reproducción concretos, los ids afectados (proyecto, rama, endpoint), y una marca de tiempo de reloj acortan el ida y vuelta drásticamente.