Errores comunes

Sin credenciales

✖ No hay sesion activa.

Ejecuta:
  plazbot init -e tu@email.com -k <jwt> -w <workspace> -z LA

Causa: no existe ~/.plazbot/config.json o esta corrupto. Solucion: corre plazbot init con tus credenciales. Pidelas al admin del workspace o sacalas del perfil de usuario en app.plazbot.com.

401 Unauthorized

✖ Token expirado o invalido.

El apiKey que usaste ya no es valido. Genera uno nuevo
en app.plazbot.com → Perfil → API Keys y vuelve a ejecutar
plazbot init.

Causa: el JWT del apiKey caduco o fue revocado. Solucion:

Entra a app.plazbot.com → Perfil → API Keys
Genera un nuevo token
Ejecuta plazbot init -e tu@email.com -k <nuevo-token> -w <workspace> -z LA

403 Forbidden

✖ Sin permisos en el workspace wok_xyz.

Tu usuario no tiene acceso a este workspace. Verifica el ID o
pide al admin que te invite.

Causa: el x-workspace-id no pertenece a tu usuario. Solucion: verifica que el workspace en ~/.plazbot/config.json sea el correcto. Si necesitas cambiar:

plazbot init -e tu@email.com -k <jwt> -w wok_CORRECTO -z LA

429 Rate Limit

✖ Rate limit. Reintenta en 12s.

Causa: muchas peticiones en poco tiempo. El backend devuelve Retry-After y Studio lo respeta. Solucion: espera el tiempo indicado. Para uso intensivo en CI, considera lotes con pausa entre llamadas:

for AGENT in $(...); do
  plazbot studio ask "..." -a "$AGENT"
  sleep 5
done

5xx Backend

✖ Backend con problemas (502 Bad Gateway). Reintenta en unos segundos.

Causa: error temporal del backend (despliegue, escalado, downtime). Solucion: reintenta. Si persiste mas de unos minutos, revisa status.plazbot.com.

Con --dev Studio imprime el body completo del error para facilitar el debug local.

Error de red

✖ No se pudo conectar al backend.

Verifica tu conexion a internet o usa --dev si trabajas
contra un backend local.

Causa: DNS, firewall corporativo, VPN o backend caido. Solucion:

Prueba curl https://api.plazbot.com/health
Si estas detras de proxy corporativo, configura HTTPS_PROXY y HTTP_PROXY
Si trabajas con backend local: plazbot studio --dev

Stream abortado (Esc)

Plazbot > Texto truncado... ✖ cancelado

Causa: presionaste Esc durante el streaming. Comportamiento esperado: no es un error real. El REPL queda listo para el proximo input.

Aunque el stream se cancele, las herramientas ya ejecutadas antes del Esc no se revierten. Si modificaste un agente y cancelas, el cambio queda aplicado en el backend.

Node version no soportada

✖ Plazbot Studio requiere Node.js >= 18.17.0

Tu version: v16.20.0

Causa: Studio usa fetch nativo + ReadableStream + ESM, disponibles desde Node 18.17. Solucion: actualiza Node:

# Con nvm
nvm install 20
nvm use 20

# Con volta
volta install node@20

Terminal sin soporte ANSI

Si los colores no se ven o aparecen secuencias raras tipo [0;32m: Causa: tu terminal no soporta ANSI o ejecutas Studio dentro de un wrapper que no propaga TTY. Solucion: usa --no-color:

plazbot studio --no-color

Alternativamente, usa un terminal moderno (iTerm2, Alacritty, Windows Terminal, VSCode integrated).

Tabla rapida de errores

Codigo	Mensaje	Accion
-	No hay sesion	Corre `plazbot init`
401	Token expirado	Regenera apiKey + `plazbot init`
403	Sin permisos	Verifica workspace
404	Agente no encontrado	Verifica ID o lista con `/agents`
429	Rate limit	Espera `Retry-After` segundos
5xx	Backend con problemas	Reintenta o revisa status
-	Network error	Verifica conexion / proxy
-	Node no soportada	Actualiza a Node 18.17+

Recolectar logs para soporte

Si necesitas reportar un bug:

# Modo verboso (imprime headers y chunks crudos)
DEBUG=plazbot:* plazbot studio --dev 2> studio-debug.log

# Compartir el log con soporte
cat studio-debug.log | pbcopy

El log nunca incluye el JWT completo. Solo los primeros y ultimos 6 caracteres. Es seguro de compartir.

CLI Plazbot

Módulos

Sin credenciales

401 Unauthorized

403 Forbidden

429 Rate Limit

5xx Backend

Error de red

Stream abortado (Esc)

Node version no soportada

Terminal sin soporte ANSI

Tabla rapida de errores

Recolectar logs para soporte

​Sin credenciales

​401 Unauthorized

​403 Forbidden

​429 Rate Limit

​5xx Backend

​Error de red

​Stream abortado (Esc)

​Node version no soportada

​Terminal sin soporte ANSI

​Tabla rapida de errores

​Recolectar logs para soporte

Sin credenciales

401 Unauthorized

403 Forbidden

429 Rate Limit

5xx Backend

Error de red

Stream abortado (Esc)

Node version no soportada

Terminal sin soporte ANSI

Tabla rapida de errores

Recolectar logs para soporte