# Errores comunes

> Errores de Plazbot Studio, por qué ocurren y cómo resolverlos

Fuente: https://developers.plazbot.com/cli/studio/errores/

### Errores comunes

Studio muestra los errores de dos formas: en la [sesión interactiva](https://developers.plazbot.com/cli/studio/repl) aparecen dentro de la conversación como un mensaje `● Plazbot` en rojo que empieza con `✖`; en la [consulta única](https://developers.plazbot.com/cli/studio/ask) 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`) |

```text
$ plazbot studio ask "List my agents"

Error: You are not signed in.
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.

```text
$ plazbot studio ask "List my agents"

Error: Too many requests.
Wait a few seconds and try again.
```

> **Nota:** 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` |

> **Importante:** 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`:

```bash
FORCE_COLOR=0 plazbot studio ask "List my agents"
```