CH 07 · Cheatsheet de Resolução de Problemas
Objetivo do Capítulo
Depois que você está em funcionamento e se depara com problemas, não entre em pânico — combine com este mapa. Os problemas mais comuns de inicialização, configuração e execução estão todos cobertos em um só lugar.
Não Consegue Iniciar
Existem apenas três armadilhas comuns para a inicialização do dsh web:
| Sintoma | Causa | Resolução |
|---|---|---|
| Inicialização reporta porta ocupada | 3080 está ocupada por outro programa | Ao iniciar, mude a porta: dsh web --port 8080 (isso faz parte do comando de inicialização, não é algo que se possa mudar em execução) |
| Navegador não abriu sozinho | Alguns ambientes não abrem o navegador automaticamente | Visite manualmente http://127.0.0.1:3080 (use a porta correspondente se você a mudou) |
| Serviço saiu sozinho durante o uso | O serviço dsh às vezes sai sozinho | Não está quebrado; basta rodar novamente quando precisar |
Erros Relacionados à Configuração
Durante a configuração do modelo, os erros se encaixam em algumas categorias — encontre o seu:
| Erro | Significado | Resolução |
|---|---|---|
MISSING_CREDENTIAL | Nenhuma chave configurada | Vá até Settings → Models para armazenar uma chave, ou forneça a variável de ambiente que ela referencia |
INVALID_CREDENTIAL | Formato da chave está errado | Verifique sua chave em busca de espaços extras ou caracteres faltando |
UNKNOWN_MODEL | Modelo não existe ou não está configurado | Verifique se o Model ID está configurado; também verifique se este provider suporta este modelo |
UNSUPPORTED_REASONING_EFFORT | Reasoning effort não suportado | Use um entre off / low / high / max |
| Fetch available models retorna 401 | A chave está errada | Verifique a chave; a descoberta de modelos chama o endpoint OpenAI-compatível GET /models. Para serviços que não fornecem esse endpoint, insira o modelo manualmente |
Erros de Requisição em Runtime
Quando uma requisição é enviada e você recebe um código de erro HTTP, é principalmente o status do lado do servidor DeepSeek, não relacionado à sua configuração. Cheatsheet oficial de códigos de erro:
| Código | Significado | Resolução |
|---|---|---|
| 401 | Falha de autenticação | Verifique se a API Key é válida ou se expirou |
| 402 | Saldo insuficiente | Recarregue na DeepSeek Open Platform |
| 422 | Erro de parâmetro | Modifique os parâmetros da requisição conforme a mensagem de erro |
| 429 | Requisições muito frequentes | Diminua a frequência de requisições, espere um momento e tente novamente (não spame) |
| 500 | Erro interno do servidor | Espere um momento e tente novamente; se continuar falhando, contate a equipe oficial |
| 502 | Erro de gateway | Serviço de modelo upstream indisponível, espere e tente novamente |
| 503 | Servidor ocupado | Carga do lado do servidor está alta, tente mais tarde |
O dsh também categoriza erros em alguns códigos internos estáveis (AUTH falha de autenticação, QUOTA cota, RATE_LIMIT limite de taxa, CONTEXT_WINDOW_EXCEEDED estouro de contexto, TRANSPORT falha de transporte de rede, etc.). Quando você ver esses códigos, leve-os ao pé da letra — geralmente é exatamente isso que significam.
Duas Pequenas Armadilhas da Interface
- Seletor de modelo mostra "Select a model" e a caixa de entrada não aceita entrada: o modelo padrão que você definiu antes aponta para um provider que foi excluído. Basta escolher um modelo novamente para recuperar.
- Não consegue encontrar uma tarefa rodada por headless: olhe na lista de sessões sob Ungrouped (CH 05 explicou: arquivos são armazenados por workspace, a exibição na UI fica em Ungrouped — duas coisas separadas).
Os Três Acessos Iniciais a Tentar Primeiro
Quando você bater em um problema que não consegue bem descrever, vá nesta ordem — resolve a maioria dos problemas:
- Verifique os logs: a saída do terminal na inicialização, ou o log de inicialização redirecionado (por exemplo,
dsh web > .dsh-startup.log 2>&1), o código de erro está bem ali. - Deixe a IA verificar a árvore de configuração por si mesma: em uma sessão, peça a ela para usar
--dump-configpara verificar a configuração, e lance perguntas do tipo "por que o modelo padrão não é o que eu quero" para ela localizar (CH 05 cobriu esse truque). - Reinicie o serviço: o serviço dsh sai sozinho de qualquer jeito, então rodar novamente muitas vezes resolve.
Se os três não te salvam, há duas situações dependendo do seu nível:
- Iniciante total (dsh é seu primeiro Agent): vá até as Issues do repositório oficial e procure a mesma palavra-chave de erro; alguém provavelmente já bateu nisso.
- Já usou ferramentas como Claude Code ou Codex: basta pedir a elas que ajudem você a resolver o problema.
O que você aprendeu neste capítulo
- [ ] Conhecer as três armadilhas de inicialização (porta ocupada / navegador não abrindo / serviço saindo sozinho) e como lidar com cada uma
- [ ] Usar a tabela de erros de configuração para lidar com
MISSING_CREDENTIAL,UNKNOWN_MODEL,UNSUPPORTED_REASONING_EFFORT - [ ] Reconhecer o significado dos códigos de erro HTTP comuns em runtime (401 / 402 / 429 / 500 / 502 / 503) e o tratamento básico
- [ ] Saber que "Select a model" travando a caixa de entrada significa que o modelo padrão aponta para um provider excluído
- [ ] Para novos problemas, tentar primeiro os três acessos iniciais (verificar logs / dump-config / reiniciar)