# Resolver problemas

Empieza por una comprobación acotada:

```sh
editorbrain version
editorbrain status
editorbrain doctor --dir ./mis-videos
```

Para revisar solo archivos locales: `editorbrain doctor --dir ./mis-videos --offline`. No repara ni instala automáticamente herramientas. Sus bloqueos, advertencias y siguientes pasos indican qué falta para la tarea concreta.

## Problemas habituales

| Lo que pasa | Qué revisar | Qué evitar |
| --- | --- | --- |
| Sesión vencida / 401 | Reautorizar la conexión que falló: CLI o MCP | Copiar cookies/claves en el chat |
| No aparece mi marca | Espacio de `status`/`workspace_info`, permisos de equipo e ID | Elegir la primera marca por similitud |
| `action_required` al instalar | El paso pendiente de MCP o selección de proyecto | Repetir todo el setup |
| Cambié preferencias y el agente usa las anteriores | `workflow check`, sincronización local y chat con skill actualizado | Sobrescribir documentos para esconder el conflicto |
| Revisión/conflicto 409 | Leer versión actual, reaplicar la intención y enviar revisión nueva | Aumentar `expectedRevision` a ciegas |
| Push `partial` / salida 2 | Leer `skipped` y `next`; actualizar la API y reintentar los documentos pendientes | Afirmar que todo está sincronizado o borrar los omitidos |
| `CHECKPOINT_UNSUPPORTED` | Actualizar la API para aceptar el checkpoint v2; conservar la copia local | Reducirlo a v1 o eliminar campos de continuidad |
| Cursor inválido | Quitar cursor al cambiar filtros y usar `nextCursor` intacto | Decodificar, fabricar o reutilizarlo en otra consulta |
| Animación no encontrada | ID, versión de escena y versión instalada | Sustituir otra sin avisar |
| Preview no carga | Volver a pedir enlace autorizado; comprobar formato y red | Guardar enlaces temporales como permanentes |
| Herramienta desactivada | `studio catalog` e integraciones realmente disponibles | Afirmar que instalar el CLI la activa |
| Créditos insuficientes | Cotización, saldo y ruta elegida | Confundir saldo externo con EditorBrain |
| Límite de búsqueda | Cupo de búsquedas del espacio | Comprar créditos asumiendo que amplían búsquedas |
| 429 | Esperar `Retry-After` y reducir concurrencia | Bucle de reintentos inmediato |
| Trabajo incierto / timeout | Consultar el mismo ID/historial | Iniciar otra generación y duplicar gasto |
| HTML local en teléfono | Solicitar copia de revisión web | Compartir `localhost` como enlace público |
| Recorte del presentador no disponible | `production matte-engines` y capacidades del sistema | Suponer que Apple Vision existe en Windows/Linux |

## Actualizaciones y errores conocidos

CLI 0.45.1 distingue rechazos reconocidos de tipo/esquema de otros HTTP 400/422.
Estos últimos siguen siendo errores de validación o petición; revisa el documento
indicado con `editorbrain validate`. Autenticación, conflictos, entradas inseguras,
servidor y red detienen el push conservando las escrituras confirmadas.
`push --dry-run` no prueba si la API acepta cada esquema.

La ayuda de una versión puede anunciar una opción cuya corrección todavía esté en revisión. Consulta [Versiones y disponibilidad](https://editorbrain.com/docs/versiones), especialmente las limitaciones de `update --dry-run` y `update --all` en 0.39.1.

## Qué enviar a soporte

Incluye versión del CLI, código de error, ID del proyecto/trabajo y pasos para reproducirlo. Indica qué esperabas y qué ocurrió. Para capturas, oculta datos personales de terceros.

No envíes API keys, cookies, tokens de OAuth, archivos `.env` ni datos de tarjeta. Usa [soporte@editorbrain.com](mailto:soporte@editorbrain.com). Un problema con un solo video no exige borrar la marca, toda la caché o tus archivos originales.