Solução de problemas

Esta página reúne os problemas mais comuns ao usar o Almirant e suas soluções. Se o seu problema não aparecer aqui, entre em contato com o suporte em [email protected].

Problemas frequentes

Problema	Causa	Solução
O IDE não conecta ao MCP	URL ou API key incorreta	Verifique se a URL é https://api.almirant.ai/mcp?projectId=<id> e se a API key é válida. Confirme que o backend está em execução se usar localhost.
"Unauthorized" ao conectar ao MCP	API key expirada ou revogada	Gere uma nova API key em Configurações > API Keys e atualize a configuração do seu IDE.
O MCP conecta, mas não vê meus projetos	projectId ausente ou incorreto	Verifique o projectId na URL. Você pode obtê-lo pela URL do navegador ao abrir o projeto no Almirant ou usando list_projects sem projectId.
Não consigo fazer login	Conta do Google não autorizada	Seu e-mail deve estar na lista de e-mails permitidos da organização. Entre em contato com o administrador para adicioná-lo.
Work items não aparecem no board	Itens arquivados ou filtro ativo	Revise os filtros ativos na barra superior do board. Se os itens estiverem arquivados, ative o filtro "Mostrar arquivados" para visualizá-los.
A IA não implementa a tarefa	Work item sem descrição suficiente	Certifique-se de que o work item tenha uma descrição detalhada com critérios de aceitação. Sem contexto, a IA não pode determinar o que implementar.
Drag and drop não funciona no board	Conflito com extensão do navegador	Desative extensões que modifiquem o DOM (ad blockers agressivos, ferramentas de acessibilidade que interceptam eventos). Teste em uma janela anônima.
O webhook não recebe eventos	URL inacessível ou HTTPS obrigatório	Verifique se a URL está acessível pela internet e usa HTTPS. Revise o registro de entregas em Configurações > Webhooks para ver os erros.
O webhook retorna 401	Assinatura não verificada corretamente	Certifique-se de usar o body bruto (raw) para calcular a assinatura HMAC, não o body processado. Verifique se o secret corresponde ao configurado.
O sprint não é encerrado	Há work items não resolvidos	Sprints podem ser encerrados com itens pendentes. Os itens não concluídos podem ser movidos para o backlog ou para o próximo sprint ao encerrar.
Erro ao importar leads (CSV)	Formato de arquivo incorreto	Verifique se o CSV usa vírgulas como separador e tem as colunas obrigatórias (name, email). Baixe o modelo na tela de importação.
O Feedback widget não aparece	Script não carregado ou chave incorreta	Verifique se o script está antes de </body>, se a URL está correta (https://cdn.almirant.ai/feedback-widget.iife.js) e se a publicKey é válida.
Erro "CORS" ao conectar pelo IDE	Backend não configura CORS para sua origem	Se usar o backend local, verifique se CORS_ORIGIN no seu .env inclui a origem correta. Em produção, isso não deveria ocorrer.
O planejamento de IA não gera resultados	Provedor de IA não configurado	Vá para Configurações > Integrações e conecte um provedor de IA (Anthropic ou OpenAI). Você precisa de pelo menos uma API key ativa.
Desempenho lento ao carregar boards grandes	Muitos itens visíveis	Use filtros para limitar os itens visíveis. Arquive itens concluídos antigos. Os boards funcionam melhor com menos de 200 itens visíveis.

Depuração avançada

Verificar a conexão MCP

Execute este comando no Claude Code para verificar se a conexão funciona:

Use a ferramenta list_projects para listar meus projetos

Se você vir seus projetos, a conexão está correta. Caso contrário:

1. Verifique se o backend está em execução (bun run dev:api no desenvolvimento local)
2. Confira a URL em .mcp.json ou .claude/settings.json
3. Verifique se a API key tem permissões para o projeto indicado
4. Revise os logs do backend para ver erros de autenticação

Verificar webhooks

Para depurar um webhook que não funciona:

1. Vá para Configurações > Webhooks e selecione o webhook
2. Revise a aba Entregas para ver tentativas recentes
3. Clique em uma entrega com falha para ver os detalhes (request, response, headers)
4. Se não houver entregas, verifique se os eventos assinados correspondem à ação que você está realizando
5. Use um serviço como webhook.site para testar se o Almirant envia as requisições corretamente

Problemas com o Feedback Widget

Se o widget não aparecer ou não funcionar:

1. Abra o console do navegador (F12 > Console) e procure erros
2. Verifique se o script carregou corretamente: digite FeedbackWidget no console. Se for undefined, o script não carregou
3. Verifique se FeedbackWidget.isReady() retorna true
4. Confirme que a publicKey está correta na configuração do projeto
5. Se usar React, certifique-se de que o componente <FeedbackWidget> está montado na árvore

Logs do navegador

Para qualquer problema com a interface web:

1. Abra o DevTools (F12)
2. Vá para a aba Console e procure erros em vermelho
3. Vá para a aba Network e filtre requisições com falha (status 4xx ou 5xx)
4. Se for relatar um bug, inclua:
   • Captura dos erros do console
   • URL da página onde ocorre
   • Navegador e versão
   • Passos para reproduzir

Dica

Se algo não funcionar como esperado, o primeiro passo é sempre verificar o console do navegador e os logs do backend. A maioria dos problemas é resolvida com informações desses dois lugares.