Errores comunes | Plazbot Docs

Sin credenciales

text

01 No hay sesion activa.
02 
03Ejecuta:
04  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 el panel de Plazbot.

401 Unauthorized

text

01 Token expirado o invalido.
02 
03El apiKey que usaste ya no es valido. Genera uno nuevo
04en el panel de Plazbot → Perfil → API Keys y vuelve a
05ejecutar plazbot init.

Causa: el JWT del apiKey caduco o fue revocado.

Solucion:

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

403 Forbidden

text

01 Sin permisos en el workspace wok_xyz.
02 
03Tu usuario no tiene acceso a este workspace. Verifica el ID o
04pide 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:

bash

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

429 Rate Limit

text

01 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:

bash

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

5xx Backend

text

01 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

text

01 No se pudo conectar al backend.
02 
03Verifica tu conexion a internet o usa --dev si trabajas
04contra 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)

text

01Plazbot > 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

text

01 Plazbot Studio requiere Node.js >= 18.17.0
02 
03Tu version: v16.20.0

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

Solucion: actualiza Node:

bash

01# Con nvm
02nvm install 20
03nvm use 20
04 
05# Con volta
06volta 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:

bash

01plazbot 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:

bash

01# Modo verboso (imprime headers y chunks crudos)
02DEBUG=plazbot:* plazbot studio --dev 2> studio-debug.log
03 
04# Compartir el log con soporte
05cat studio-debug.log | pbcopy

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