# Troubleshooting

Problemas comuns, do sintoma à solução. Para diagnosticar com mais detalhe, rode qualquer comando com -v (verbose).

# Índice rápido

# Plugin instala mas não registra

Sintoma: o mpm diz OK ... installed successfully, mas o plugin não aparece em Settings → Plugins nem na tabela plugins.

Causa mais comum: layout docroot (Mautic 5/6 composer). Os arquivos foram pra /var/www/html/plugins, mas o Mautic lê de /var/www/html/docroot/plugins.

Diagnóstico:

docker exec <container> test -f /var/www/html/docroot/app/AppKernel.php && echo "layout docroot"
docker exec <container> ls /var/www/html/docroot/plugins
mpm console -i prod -- doctrine:query:sql \
  "SELECT bundle, is_missing FROM plugins WHERE bundle LIKE '%<Nome>%'"

Solução:

1. Atualize o mpm (mpm self-update) — a v0.2.1+ detecta e corrige automaticamente.
2. Reinstale o plugin. Confirme no log a linha Deploying ...Bundle to <container>:/var/www/html/docroot/plugins/....
3. Se for um layout customizado, force: mpm --plugins-dir <real> install ....
4. Limpe diretórios mortos antigos: docker exec <container> rm -rf /var/www/html/plugins/<Bundle>.

Ver Layout do Mautic.

# Validação falha com "Missing fields"

Sintoma: [FAIL] Missing fields: name, version numa instalação, mesmo o config.php tendo os campos.

Causa: versões antigas do mpm só liam config.php com aspas simples ('name' => '...'). Plugins com aspas duplas ("name" => "...") eram marcados como faltando campos.

Solução: atualize o mpm (mpm self-update) — corrigido na v0.2.1. Se precisar instalar já: mpm install <plugin> -i prod --force (o aviso é benigno quando o config.php está correto).

# Erros de autenticação

# `426 fingerprint_required`

O mpm é antigo e não envia o header X-MPM-Fingerprint.

mpm self-update

# `403 key_revoked`

A key foi usada fora do ambiente onde foi vinculada (fingerprint mismatch) e foi revogada permanentemente. Não há reset.

Solução: peça uma key nova ao admin e use uma key por instalação. Ver API key e fingerprint.

# `401`

Key inválida ou ausente. Confira a cascata:

echo "$MPM_API_KEY"
grep api_key /opt/mpm/config.toml
mpm --api-key mpm_live_xxx catalog refresh   # testa com a key explícita

# Download falha ou 404

Sintoma: a instalação falha no passo de download, ou erro de "File not found in storage".

Diagnóstico:

mpm -v install <plugin> -i prod    # mostra a signed URL e o tamanho
mpm catalog info <plugin>          # versão/checksum esperados

Causas possíveis:

• Plugin sem direito na sua licença → confirme com mpm catalog search.
• Artefato ainda não publicado no CDN (lado do marketplace) → é problema de publicação, não do mpm. Contate o admin.
• Catálogo local desatualizado → mpm catalog refresh.

# Container não encontrado

Sintoma: Container '<x>' is not running ou instância não resolve.

docker ps                         # o container está de pé?
mpm instance list                 # o nome bate?
mpm instance discover             # redescobrir
mpm instance status prod

Se o nome do container mudou, remova e recadastre a instância.

# Mautic fora do ar após instalar

Sintoma: o site não responde depois de uma instalação.

O mpm faz health check (etapa 14) e reverte o deploy em falha. Se mesmo assim houver problema:

mpm rollback <plugin> -i prod      # volta o backup
mpm console -i prod -- cache:clear
docker exec <container> tail -50 /var/www/html/var/logs/mautic_prod-$(date +%F).php

Nota: um WARN de health check com URL placeholder (ex.: https://m6e2e.mtc.codes/) é esperado quando o domínio não resolve publicamente. Cheque localmente: docker exec <container> curl -s -o /dev/null -w "%{http_code}" http://localhost/.

# Coletando informação para suporte

mpm --version
mpm -v <comando que falhou> 2>&1 | tee /tmp/mpm-debug.log
mpm list -i prod -o json