Errores comunes
Studio muestra los errores de dos formas: en la sesión interactiva aparecen dentro de la conversación como un mensaje ● Plazbot en rojo que empieza con ✖; en la consulta única salen en stderr como Error: ... con una pista debajo, y el comando termina con código 1 (con --json, como {"error":{"message","code","hint"}}). Los mensajes están en inglés.
Antes de abrir Studio
| Mensaje | Causa | Solución |
|---|---|---|
You are not signed in. | No hay sesión guardada ni variables PLAZBOT_API_KEY / PLAZBOT_WORKSPACE_ID | plazbot login, o define ambas variables |
The Studio REPL needs an interactive terminal. | plazbot studio sin TTY (CI, pipe, redirección) | Usa plazbot studio ask "List my agents" |
--json only works with a one-shot prompt. | --json sin -m | plazbot studio ask "List my agents" --json |
The message is empty. | Mensaje vacío en ask o -m | Pasa un texto: plazbot studio ask "List my agents" |
Plazbot CLI requires Node.js >=18.17.0. Current version: 16.20.0 | Versión de Node antigua | Actualiza Node (por ejemplo nvm install 20) |
01$ plazbot studio ask "List my agents"0203 Error: You are not signed in.04 Run `plazbot login`, or set PLAZBOT_API_KEY and PLAZBOT_WORKSPACE_ID.
Errores de la API
| Caso | Sesión interactiva | Consulta única | Solución |
|---|---|---|---|
| 401 | ✖ Token expired or invalid. Run plazbot login. | Your session is invalid or expired. | plazbot login |
| 403 | ✖ No permission for this workspace. | You do not have permission for this workspace. | Revisa el workspace activo con plazbot whoami |
| 429 | ✖ Rate limit reached. Wait a few seconds and try again. | Too many requests. | Espera unos segundos y reintenta |
| 5xx | ✖ The backend returned error 502. Retry in a few seconds. | Plazbot Studio error (HTTP 502). | Reintenta en unos segundos |
| Otro HTTP | ✖ HTTP 400 Bad Request | Studio request failed (HTTP 400 Bad Request). | Revisa el mensaje y las opciones |
| Sin red | ✖ Could not reach the Plazbot API. Check your internet connection. | Could not reach the Plazbot API. (puede incluir el código, por ejemplo (ENOTFOUND)) | Revisa tu conexión, DNS, VPN o proxy |
En la consulta única, si la API devuelve un mensaje propio en el cuerpo de la respuesta (401, 403, 429 u otros 4xx), se muestra ese mensaje en lugar del genérico.
01$ plazbot studio ask "List my agents"0203 Error: Too many requests.04 Wait a few seconds and try again.
Studio no reintenta automáticamente ante un 429 ni ante un 5xx. En scripts con muchas llamadas, agrega una pausa entre ellas (sleep 5).
Errores durante la respuesta
| Mensaje | Causa | Solución |
|---|---|---|
✖ <mensaje> (chunk error) | Studio devolvió un error en medio del stream; los pasos en curso se marcan como fallidos | Reintenta o reformula el pedido. En ask el código de salida es 1 |
✗ Could not save agent — <motivo> | Una herramienta falló (por ejemplo, configuración inválida o límite de agentes del plan) | Studio explica el motivo en el texto; corrige y vuelve a intentar |
○ Could not load agent — Agente 'age_AbcDef123' no encontrado en este workspace. | El agente no existe en el workspace | Revisa el id con /agents |
Response cancelled. | Presionaste Esc | No es un error; el cuadro de texto queda disponible |
Cancelled. | Ctrl+C durante studio ask | Código de salida 130 |
Cancelar no revierte lo que una herramienta ya hizo en el backend. Si el agente ya se guardó antes del Esc, el cambio queda aplicado.
Errores de slash commands
| Mensaje | Causa | Solución |
|---|---|---|
Unknown command: /deploy. Run /help to see the list. | El comando no existe | /help |
Usage: /load <agentId> | /load sin id | /load age_AbcDef123 |
No agent configuration loaded. Create one first or use /load <id>. | /save o /export sin configuración en la sesión | Carga el agente con /load o crea uno |
Could not write the file: <motivo> | /export no pudo escribir (carpeta inexistente, sin permisos) | Usa otra ruta: /export ~/ventas.json |
Nothing to compact yet. | /compact sin mensajes | Conversa primero |
Conexión de canales
| Mensaje | Causa | Solución |
|---|---|---|
No connection detected | Pasaron 5 minutos sin detectar la conexión | Pídele a Studio que genere un link nuevo |
Could not activate the integration | Falló la activación del canal | Reintenta; si persiste, conecta el canal desde el panel |
Connection cancelled | Presionaste Esc durante la espera | Pide un link nuevo cuando quieras |
Colores en la terminal
Si ves secuencias raras como [0;32m, tu terminal o el wrapper no interpreta colores ANSI. Desactívalos con FORCE_COLOR=0:
01FORCE_COLOR=0 plazbot studio ask "List my agents"