Para administradores
← Todos os tópicos

Solução de problemas

Sintoma, causa e o que fazer – da falta de acesso à caixa de e-mail a um segredo expirado.

Primeiro, o panorama geral, a partir do diretório da instalação:

./draften status      # version, health of both web colours and the workers, HTTPS, database dumps

Depois, com mais detalhes:

docker compose ps                        # are the services up, is the database healthy?
docker compose logs --tail 50 worker     # the worker's last entries
docker compose run --rm worker node diag.mjs mailbox@company.com

O último faz o mesmo que Testar a conexão na interface: pega o acesso guardado para a caixa de e-mail, obtém um token, mostra as permissões dele (nunca o próprio token) e lê a Caixa de Entrada.

Erros comuns

SintomaCausaO que fazer
set DB_PASSWORD in .env na inicializaçãofaltam as senhas do banco de dadospreencha o .env
mailbox … has no access yeta caixa de e-mail não tem registro nem conta conectadaa página da caixa de e-mail → Acesso aos e-mails
“A organização não tem um cliente Microsoft 365 ou Google configurado” ao conectar uma caixa de e-mail com a contaa organização não tem cliente no cartão Entrada com conta e conexão de caixas de e-mailum proprietário da organização o adiciona – veja Microsoft 365 ou Google Workspace, cliente da organização
Graph … 401 … invalid_clientclient secret errado ou expiradoum novo secret no registro e, depois, o teste de conexão
Graph … 403 … AppOnly AccessPolicya application access policy ainda não entrou em vigor, ou a caixa de e-mail não está no grupoespere (às vezes horas) e repita o teste; adicione a caixa de e-mail ao grupo
Graph … 403 … ErrorAccessDeniedfalta o consentimento do administradorno Entra, Grant admin consent no registro
Category not added … MailboxSettingsfalta a permissão MailboxSettings.ReadWrite; o marcador funciona, só que sem coradicione a permissão e dê o consentimento
No active assistant in the databaseo assistente está desativado, ou os dados iniciais não foram criadosative o assistente; confira o log de inicialização
o assistente é pulado (“no prompts yet”)o assistente não tem instruções escritasconclua a configuração guiada ou escreva as instruções à mão
a amostra na configuração guiada mostra dados insuficienteso proprietário respondia antes de outro endereço (por exemplo, antes de uma mudança de domínio), e a configuração guiada não conta essas respostas como deleadicione o endereço no campo Outros endereços da caixa de e-mail (junto da amostra, no passo Período ou na página da caixa de e-mail) e escolha a amostra de novo; o endereço completo, não só o domínio
Draft without signature / links outside the allowed domainso rascunho não passou em uma verificaçãoexamine a mensagem – pode ser uma tentativa de falsificação
Limit reachedo limite diário ou por remetenteaumente-o só quando a enxurrada de e-mails for legítima
Model refused to answero filtro de segurança do modelotrate a mensagem à mão
Model exhausted max_iterationso modelo entrou em loop nas ferramentasé repetido duas vezes; se continuar acontecendo, aprimore a instrução do tipo Tarefa
ECONNREFUSED … 3306o banco de dados caiu ou ainda não subiudocker compose ps, docker compose logs db
a barra “A licença expirou” ou “A instalação não tem licença”, os assistentes não escrevem nadaa licença está faltando ou expiroucarregue uma licença válida – veja A licença
o serviço web fica fora do ar por um instante e as requisições em andamento se perdem; no log do serviço web (docker compose logs web-blue web-green) aparece uma reinicializaçãouma requisição ultrapassou o limite rígido de memória do PHP (a partir do PHP 8.5.12, o dobro de memory_limit) e o PHP encerrou todo o processo webo Docker inicia o serviço web de novo sozinho, geralmente em algumas dezenas de segundos; se continuar acontecendo, encontre no log a requisição que ultrapassou o limite
uma atualização terminou com erroa nova versão não ficou saudável; a anterior continua atendendoo erro em Solicitações ou na saída de ./draften update; ./draften status
o serviço web retorna 502 depois de reiniciar o servidorversões anteriores a 30 de outubro de 2026 trocavam o serviço web de um jeito que fazia o Docker considerar o proxy parado manualmente, e por isso ele não o iniciava de novo quando a máquina reiniciavano diretório da instalação, docker compose up -d --no-deps proxy; a atualização para a versão de 30 de outubro de 2026 ou mais nova resolve de vez
“O último backup diário falhou” no cartão Backups do banco de dadoso dump do banco de dados falhou (a mensagem está no cartão); uma nova tentativa é feita uma hora depoisexecute ./draften backup e leia o erro; confira o espaço livre em disco (df -h) e ./draften status

Quando o log não mostra

Uma rodada manual avulsa

docker compose run --rm worker node worker.mjs --dry-run

Ela passa uma vez por todos os assistentes ativos e força o modo de teste – nada é gravado nos e-mails. Útil para conferir se tudo funciona.

Quando você precisa da nossa ajuda

./draften diagnose

grava um arquivo diagnose-<time>.tar.gz com o status da instalação, as versões, a configuração sem segredos e o final dos logs. Envie-o para nós.

Antes de enviar o arquivo, confira o conteúdo: os logs podem conter endereços e assuntos dos e-mails processados. Nada sai do servidor sozinho.

Versão em texto