CH 07 · Hoja de referencia rápida para resolución de problemas
Objetivo del capítulo
Una vez que estés en marcha y te encuentres con problemas, no entres en pánico — busca en este mapa. Los problemas más comunes de arranque, configuración y ejecución están cubiertos en un solo lugar.
No arranca
Solo hay tres obstáculos comunes para el arranque de dsh web:
| Síntoma | Causa | Solución |
|---|---|---|
| El arranque indica puerto ocupado | 3080 está tomado por otro programa | Al arrancar, cambia de puerto: dsh web --port 8080 (esto es parte del comando de arranque, no algo que puedas cambiar en ejecución) |
| El navegador no se abrió solo | Algunos entornos no lanzan el navegador automáticamente | Visita manualmente http://127.0.0.1:3080 (usa el puerto correspondiente si lo cambiaste) |
| El servicio se cierra solo mientras se usa | El servicio dsh a veces se cierra solo | No está roto; vuelve a ejecutarlo cuando lo necesites |
Errores relacionados con la configuración
Durante la configuración del modelo, los errores se dividen en unas pocas categorías — busca el tuyo:
| Error | Significado | Solución |
|---|---|---|
MISSING_CREDENTIAL | No hay clave configurada | Ve a Ajustes → Modelos para guardar una clave, o proporciona la variable de entorno a la que se referencia |
INVALID_CREDENTIAL | El formato de la clave es incorrecto | Comprueba tu clave por espacios sobrantes o caracteres que falten |
UNKNOWN_MODEL | El modelo no existe o no está configurado | Comprueba si el Model ID está configurado; comprueba también si este provider admite este modelo |
UNSUPPORTED_REASONING_EFFORT | Nivel de razonamiento no soportado | Usa uno de off / low / high / max |
| Obtener modelos disponibles devuelve 401 | La clave es incorrecta | Comprueba la clave; el descubrimiento de modelos llama al endpoint compatible con OpenAI GET /models. Para servicios que no proporcionen ese endpoint, introduce el modelo manualmente |
Errores de petición en tiempo de ejecución
Cuando se envía una petición y obtienes un código de error HTTP, la mayor parte de las veces es el estado del lado del servidor de DeepSeek, sin relación con tu configuración. Hoja de referencia rápida de códigos de error oficial:
| Código | Significado | Solución |
|---|---|---|
| 401 | Fallo de autenticación | Comprueba si la API Key es válida o ha caducado |
| 402 | Saldo insuficiente | Recarga en la Plataforma Abierta DeepSeek |
| 422 | Error de parámetros | Modifica los parámetros de la petición según el mensaje de error |
| 429 | Peticiones demasiado frecuentes | Baja la frecuencia de peticiones, espera un momento y reintenta (no spamees) |
| 500 | Error interno del servidor | Espera un momento y reintenta; si sigue fallando, contacta con el equipo oficial |
| 502 | Error de pasarela | El servicio de modelo upstream no está disponible, espera y reintenta |
| 503 | Servidor ocupado | Carga alta del lado del servidor, reintenta más tarde |
dsh también categoriza los errores en unos pocos códigos internos estables (AUTH fallo de autenticación, QUOTA cuota, RATE_LIMIT límite de tasa, CONTEXT_WINDOW_EXCEEDED desbordamiento de contexto, TRANSPORT fallo de transporte de red, etc.). Cuando veas estos códigos, tómalos al pie de la letra — suelen ser exactamente lo que dicen.
Dos pequeños obstáculos de la interfaz
- El selector de modelo muestra "Select a model" y el cuadro de entrada no acepta texto: el modelo predeterminado que fijaste antes apunta a un provider que fue eliminado. Solo vuelve a elegir un modelo para recuperarte.
- No encuentras una tarea ejecutada por headless: busca en la lista de sesiones bajo Sin agrupar (CH 05 explicó: los archivos se almacenan por workspace, la visualización en UI va a Sin agrupar — son dos cosas separadas).
Los tres recursos a probar primero
Cuando te encuentres con un problema que no sabes describir bien, ve en este orden — resuelve la mayoría de los problemas:
- Revisa los logs: la salida del terminal al arrancar, o el log de arranque redirigido (p. ej.
dsh web > .dsh-startup.log 2>&1), el código de error está ahí mismo. - Deja que la IA revise el árbol de configuración por sí misma: en una sesión, pídele que use
--dump-configpara revisar la configuración, y lánzale la pregunta tipo "por qué el modelo predeterminado no es el que quiero" para que lo localice (CH 05 cubrió este truco). - Reinicia el servicio: el servicio dsh se cierra solo de todas formas, así que volver a ejecutarlo a menudo lo arregla.
Si los tres no te salvan, hay dos situaciones según tu nivel:
- Principiante total (dsh es tu primer Agent): ve a los Issues del repo oficial y busca la misma palabra clave de error; probablemente alguien ya lo ha tenido.
- Ya has usado herramientas como Claude Code o Codex: simplemente pídeles que te ayuden a resolver el problema.
Lo que aprendiste en este capítulo
- [ ] Conoces los tres obstáculos de arranque (puerto ocupado / navegador que no abre / servicio que se cierra solo) y cómo manejar cada uno
- [ ] Usas la tabla de errores de configuración para manejar
MISSING_CREDENTIAL,UNKNOWN_MODEL,UNSUPPORTED_REASONING_EFFORT - [ ] Reconoces el significado de los códigos de error HTTP comunes en tiempo de ejecución (401 / 402 / 429 / 500 / 502 / 503) y su manejo básico
- [ ] Sabes que "Select a model" bloqueando el cuadro de entrada significa que el modelo predeterminado apunta a un provider eliminado
- [ ] Para nuevos problemas, pruebas primero los tres recursos (revisar logs / dump-config / reiniciar)