cPanel + Dovecot: Erro `doveadm exit code 68` — Diagnóstico e Correção Definitiva

Durante a rotina de administração de servidores, principalmente no pós-migração de contas, é comum encontrar inconsistência no uso de disco de e-mail no cPanel (Jupiter). O sintoma no painel costuma ser genérico: quota que não abre, tela travada ou leitura incompleta das caixas.

Quando você desce para CLI, o erro real aparece:

doveadm: Error: cmd mailbox status: Mailbox INBOX.user@domain.com: Failed to lookup mailbox status: Mailbox doesn't exist
"/usr/bin/doveadm" reported error code "68"

Isso não é “bug aleatório” de software. É descompasso entre metadado lógico de mailbox e estrutura física Maildir no disco.

---

1) Diagnóstico de causa-raiz: estado “zumbi” de mailbox

O que vi em campo foi sempre o mesmo padrão: o Dovecot conhece a conta (namespace/registro), mas ao buscar status da INBOX no filesystem, não encontra estrutura válida.

Causas raízes mais comuns

Migração incompleta: conta criada em etc/passwd/shadow, mas mail/ não veio inteiro no rsync.
Restore seletivo: restaurou config sem restaurar dados brutos da caixa.
Permissão inconsistente: pasta existe, mas ownership/modo impedem leitura de cur/new/tmp.
Sincronização interrompida: rsync finalizado com erro parcial e ninguém validou estrutura de cada mailbox.

Esse cenário gera o mailbox “zumbi”: existe para o sistema lógico, mas não existe como Maildir íntegro.

---

2) Verificação de consistência em disco

Primeira validação objetiva:

ls -la /home/usuario_cpanel/mail/dominio.com/conta_email/

Uma Maildir válida precisa ter obrigatoriamente:

cur/
new/
tmp/

Se uma dessas pastas não existe, o Dovecot pode retornar exit code 68 em operações de status/index.

Teste complementar de confirmação

Tentar criar mailbox e receber “already exists” é forte indicativo de inconsistência lógico-física.

Também valido o status direto:

doveadm mailbox status -u conta@dominio.com messages INBOX

Se falhar com “Mailbox doesn't exist”, mas a conta existe no painel, está confirmado o estado zumbi.

---

3) Correção cirúrgica (conta isolada)

Quando o problema está concentrado em poucas caixas, corrigi manualmente para reduzir tempo de indisponibilidade.

3.1 Reconstruir estrutura Maildir

cd /home/usuario/mail/dominio.com/email/
mkdir -p cur new tmp
chown -R usuario:mail .
chmod -R 700 .

3.2 Forçar resync e indexação

doveadm force-resync -u user@domain.com INBOX
doveadm index -u user@domain.com INBOX

Isso reidrata índices e reestabelece leitura consistente de status.

3.3 Validação pós-correção

doveadm mailbox status -u user@domain.com messages INBOX

Se o comando retorna contagem de mensagens sem erro, a mailbox voltou ao estado operacional.

---

4) Correção em massa (cenário enterprise)

Em servidor com dezenas/centenas de domínios, correção manual é fonte de erro humano. Nesse caso usei o fluxo interno do cPanel para reconstrução controlada.

4.1 Rebuild de Maildir por domínio

/scripts/rebuildmaildir --force dominio.com

4.2 Reindexação global no Dovecot

doveadm index -A '*'

Detalhe crítico: manter '*' entre aspas simples evita expansão prematura do shell.

4.3 Conferência amostral após operação

doveadm mailbox status -u conta1@dominio.com messages INBOX
doveadm mailbox status -u conta2@dominio.com messages INBOX

Faço validação por amostragem de contas com maior volume e depois monitoração de ticket no painel.

---

5) Armadilha comum de sintaxe no `doveadm`

Erro clássico de operação:

doveadm index -A -u conta@dominio.com

Isso está errado porque:

-A = todos os usuários.
-u = usuário específico.

São escopos mutuamente exclusivos. Misturar os dois gera comando inconsistente.

Regra prática:

operação global -> use -A.
operação pontual -> use -u.

---

6) Playbook pós-migração para não abrir débito técnico

Toda migração de e-mail precisa de validação ativa. Esse foi o playbook que padronizei:

Finalizou rsync de mailbox -> rodar rebuild:

/scripts/rebuildmaildir --force dominio.com

Após DNS/serviço estabilizados -> reindexar Dovecot:

doveadm index -A '*'

Validar contas críticas:

doveadm mailbox status -u user@domain.com messages INBOX

Conferir painel de uso de disco e abertura de Webmail.

Registrar evidência no change log da migração (comandos + horário + resultado).

---

7) Boas práticas de hardening operacional

Não tratar Maildir como pasta comum; tratar como dado crítico de produção.
Evitar alterações manuais sem log de mudança.
Fazer rsync com validação de retorno e conferência de estrutura.
Revisar ownership e permissão após restore.
Criar checklist obrigatório de pós-migração antes de liberar chamado como concluído.

---

Conclusão

O exit code 68 do doveadm é indicador de integridade quebrada entre camada lógica e física de e-mail. Ignorar isso gera efeito cascata: quota inconsistente, Webmail com erro, ticket recorrente e perda de confiança do cliente.

Quando você corrige causa-raiz (Maildir + index), o ambiente estabiliza.

Infra madura não é a que “reinicia serviço para voltar”; é a que valida estrutura, reconstrói com método e deixa evidência técnica do que foi feito.

Este post está licenciado sob CC BY-NC.