Erros comuns e como remediar
Compatível com ww1.14.0
Esta página é o índice de remediação: cada erro aponta para o comando que resolve.
A regra geral: STOP + mensagem apontando para o comando certo
Seção intitulada “A regra geral: STOP + mensagem apontando para o comando certo”Quando a skill workforce-context detecta um problema de conexão, token ou contexto, ela NÃO tenta contornar. Ela para (STOP) e mostra uma mensagem padronizada que aponta para o comando que resolve. A exceção são os comandos que rodam em modo de melhor esforço (como /ww:config:preferences e os /ww:doc:*): eles avisam o que está faltando e seguem com o que têm.
As mensagens da skill vêm em inglês e, quando o erro veio do WiseWork, trazem um identificador (req: <id>) — guarde-o, ele liga o erro ao log local e ao registro do servidor.
Tabela de erros
Seção intitulada “Tabela de erros”| Erro / sintoma | Causa mais comum | Comando que resolve | Onde investigar |
|---|---|---|---|
| ”Workforce MCP not configured” | Claude Code não foi reiniciado após a instalação, ou o servidor não foi registrado (por exemplo, instalação com --skip-mcp) | npx -y wisework@latest install --slug=<slug> de novo e reiniciar o Claude Code; como alternativa manual, /ww:config:mcp | npx -y wisework@latest status |
”WORKFORCE_TOKEN expired” / “is invalid” / “has been revoked” | Token expirado, não reconhecido ou revogado | npx -y wisework@latest install --slug=<slug> de novo: o novo pareamento gera um token e o MCP registrado pelo instalador é trocado sem perguntar (se o MCP workforce foi registrado por fora do instalador, ele pergunta se substitui — responda sim); como alternativa manual, /ww:config:mcp | npx -y wisework@latest status |
| ”Could not reach the Workforce API (network/timeout)“ | Rede, tempo esgotado ou BASE_URL errado — não é problema de token | Conferir a conexão e o BASE_URL e tentar de novo | ~/.claude.json (bloco env do MCP workforce) |
| “No Workforce context found” | init nunca rodou neste projeto | /ww:init | — |
O /ww:init para sem resolver sua identidade | O token não está ligado a um membro do time | Pedir ao admin que vincule sua conta a um membro e rodar o instalador de novo | — |
| “Invalid task status: X. Valid values for this project are: …” | Você usou um status que não existe neste projeto | Usar uma das chaves listadas na própria mensagem | Conceito: ticket × título + status |
/ww:init <nome> não fixa o projeto que você queria | O nome não bate com exatamente um projeto seu | Escolher na pergunta que o comando faz (até 4 opções, ou digitar outro) | Confira o nome exato do projeto |
Ticket listado como não encontrado (em task:claim, task:status) | Ticket não existe neste projeto | Pedir a lista com /ww:task:list | O número é por projeto: pode ser de outro |
Mais de um item com o mesmo trecho de título (em backlog:show, features:show) | O trecho do título bateu com mais de um | Escolher na pergunta que o comando faz, ou colar o UUID | Sem nenhum resultado, o comando lista os títulos disponíveis |
/ww:review:task lista as tasks disponíveis e para | Não existe .dr_ai/tasks/<nome>/ para a task informada | Usar /ww:review:pr | Referência review:pr |
Verificação falhou (em implement, fix) | Erro de tipos, lint ou build | O próprio comando corrige os erros novos antes de concluir; erros já existentes em outros arquivos são só reportados | O verificador detectado pela skill typecheck-config |
Diagnóstico passo a passo
Seção intitulada “Diagnóstico passo a passo”Quando algo não funciona e a mensagem não está na tabela acima:
- Rode
/ww:initde novo. Ele é o comando que valida a conexão e o token ao vivo. - Se persistir, rode
npx -y wisework@latest statusno terminal para ver se o plugin e o servidor MCP estão registrados; para corrigir, rode o instalador de novo (npx -y wisework@latest install --slug=<slug>) ou, à mão, o/ww:config:mcp. - Se persistir, abra uma issue com: o comando exato, a mensagem completa (com o
(req: <id>), se houver), o output de/ww:init(sem token) e as linhas correspondentes de.dr_ai/logs/mcp_access_<AAAAMMDD>.jsonl.