> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plazbot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errores comunes

> Diagnostico rapido de errores en Studio y como resolverlos

## Sin credenciales

```text theme={null}
✖ 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

```text theme={null}
✖ 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**:

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

***

## 403 Forbidden

```text theme={null}
✖ 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:

```bash theme={null}
plazbot init -e tu@email.com -k <jwt> -w wok_CORRECTO -z LA
```

***

## 429 Rate Limit

```text theme={null}
✖ 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 theme={null}
for AGENT in $(...); do
  plazbot studio ask "..." -a "$AGENT"
  sleep 5
done
```

***

## 5xx Backend

```text theme={null}
✖ 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`.

<Tip>
  Con `--dev` Studio imprime el body completo del error para facilitar el debug local.
</Tip>

***

## Error de red

```text theme={null}
✖ 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)

```text theme={null}
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.

<Warning>
  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.
</Warning>

***

## Node version no soportada

```text theme={null}
✖ 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:

```bash theme={null}
# 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`:

```bash theme={null}
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:

```bash theme={null}
# 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
```

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