Erro 500 no Magento 2: encontre a causa em 9 passos sem apagar as pistas

Erro 500 no Magento 2 pode derrubar toda a loja, afetar apenas o Admin ou aparecer em uma rota específica, como produto, carrinho ou checkout. Embora o navegador mostre uma resposta genérica, a causa costuma deixar rastros nos logs da aplicação, do PHP, do servidor web ou de algum serviço dependente.

Antes de limpar caches, recompilar tudo ou restaurar um backup, registre o cenário e preserve as evidências. Os nove passos abaixo ajudam a encontrar a origem do problema e evitam que uma ação precipitada esconda a mensagem realmente útil.

Erro 500 no Magento 2: delimite o impacto primeiro

Descubra se o erro afeta todas as páginas ou somente uma operação. Teste a página inicial, uma categoria, um produto, o carrinho e o Admin. Use uma janela anônima e, quando possível, compare clientes autenticados e visitantes.

Anote horário exato, URL, visão de loja, ação executada e alteração anterior ao incidente. Um erro iniciado logo após deploy, atualização de extensão, mudança de PHP ou configuração de infraestrutura direciona a investigação, mas ainda precisa ser confirmado pelos registros.

1. Confirme o código HTTP e preserve a resposta

Uma página branca ou uma mensagem de erro do proxy não comprova, sozinha, que o Magento retornou HTTP 500. A resposta também pode ser 502, 503, 504, 403 ou um redirecionamento incorreto.

Consulte a aba Network das ferramentas do navegador ou execute, de uma máquina autorizada:

curl -I https://www.exemplo.com.br/rota-afetada

Registre cabeçalhos, horário e camada que respondeu. Se houver CDN, balanceador ou Varnish, compare o acesso público com a origem usando os procedimentos permitidos pela infraestrutura. Não desative essas camadas em produção apenas para testar.

2. Leia os logs correspondentes ao mesmo horário

Comece pelos arquivos normalmente encontrados em var/log/, principalmente exception.log, system.log e, quando habilitado, debug.log. Dependendo do ambiente, também será necessário consultar os logs do PHP-FPM, Nginx, Apache, contêiner ou plataforma de hospedagem.

tail -n 200 var/log/exception.log
tail -n 200 var/log/system.log

Procure a primeira exceção relacionada ao horário da requisição, não somente a última linha. Uma falha original pode gerar vários erros secundários. Preserve uma cópia antes de rotacionar ou excluir arquivos e remova tokens, cookies, dados pessoais e credenciais antes de compartilhar trechos.

3. Verifique modo de manutenção e estado da aplicação

Confirme se a loja permaneceu em modo de manutenção depois de um deploy interrompido:

php bin/magento maintenance:status

O modo de manutenção costuma produzir uma indisponibilidade controlada, mas personalizações no tratamento de erros ou no servidor podem transformar a resposta em outro código. Não o desative até confirmar se há atualização de banco, compilação ou publicação de arquivos ainda em andamento.

Verifique também espaço em disco e quantidade de inodes. A falta de espaço pode impedir a gravação de sessões, caches, arquivos temporários e logs, criando sintomas diferentes em várias páginas.

df -h
df -i

4. Examine proprietário e permissões sem usar chmod 777

Arquivos publicados por outro usuário podem impedir que o servidor web leia o código ou grave nos diretórios necessários. Compare proprietário, grupo e permissões com o padrão definido para o ambiente:

ls -ld . var generated pub/static pub/media
namei -l pub/index.php

Evite aplicar permissões abertas de forma recursiva. Além do risco de segurança, isso pode mascarar o conflito entre o usuário do deploy, o PHP-FPM e os processos de cron. Corrija somente depois de identificar qual usuário deve ler ou gravar em cada diretório.

5. Compare o PHP da linha de comando com o PHP-FPM

É possível que o comando do Magento funcione no terminal enquanto a loja retorna erro 500. Isso acontece quando CLI e PHP-FPM usam versões, extensões, limites ou arquivos php.ini diferentes.

php -v
php --ini
php -m
php -i | grep memory_limit

Nos logs, procure mensagens sobre memória esgotada, extensão ausente, tipo incompatível ou função indisponível. Aumentar o limite de memória pode aliviar um sintoma, mas não corrige loops, coleções excessivas ou módulos incompatíveis. Compare os requisitos do projeto antes de trocar a versão do PHP.

6. Relacione o erro ao último deploy ou comando Composer

Se o problema começou após uma publicação, compare o release atual com o anteriormente validado. Confirme se composer.lock, pasta vendor, código personalizado e arquivos de configuração pertencem à mesma versão.

Não apague o composer.lock nem execute uma atualização geral para tentar reconstruir dependências. Quando houver conflito de pacotes, siga um diagnóstico controlado de erro do Composer no Magento 2.

Comandos como setup:di:compile e setup:static-content:deploy devem fazer parte de um processo compatível com o modo da aplicação e ser validados fora da produção. Repeti-los sem ler a exceção pode substituir artefatos úteis sem corrigir a origem.

7. Investigue módulos e interceptadores pela pilha da exceção

A pilha registrada no log pode apontar para um plugin, observer, preferência, template ou classe personalizada. Identifique o primeiro trecho pertencente a app/code ou a um pacote de terceiro, mas não conclua que ele é culpado apenas por aparecer na pilha.

Compare a versão instalada, as alterações recentes e as dependências do módulo. Desativar extensões diretamente em produção pode interromper checkout, pagamentos, atributos ou tarefas agendadas. Reproduza o problema em homologação e remova um componente por vez, mantendo um plano de reversão.

8. Confirme banco de dados, cache, busca e filas

O Magento pode responder com erro 500 quando não consegue acessar banco de dados, Redis, mecanismo de busca ou outro serviço exigido durante a requisição. Procure nos logs mensagens de conexão recusada, timeout, falha de resolução de nome, autenticação ou limite de conexões.

Não teste credenciais expondo senhas no histórico do terminal. Use ferramentas autorizadas pela infraestrutura e confirme conectividade a partir do mesmo host ou contêiner da aplicação. Se o erro envolver mudança de banco ou compatibilidade, consulte o roteiro sobre migração do banco de dados no Magento.

Uma dependência indisponível pode afetar apenas determinadas rotas. A busca pode falhar em categorias enquanto páginas institucionais continuam acessíveis; problemas de sessão podem atingir clientes autenticados; falhas no gateway podem surgir somente ao finalizar o pedido.

9. Isole a rota e valide a correção de ponta a ponta

Se o erro aparece apenas no Admin, verifique sessão, cookies, autenticação e permissões antes de tratar o problema como indisponibilidade geral. O guia sobre Magento 2 que não entra no Admin ajuda a separar esses cenários.

Para uma rota de frontend, reproduza a falha com o mesmo produto, cliente, CEP, moeda e visão de loja. Depois da correção, valide pelo menos:

• página inicial, categorias, busca e produtos;
• login, criação de conta e recuperação de senha;
• carrinho, cálculo de entrega e cupons;
• checkout com os principais meios de pagamento;
• Admin, cron, consumidores de fila e integrações;
• logs da aplicação e monitoramento após a liberação.

Se o erro estiver concentrado na compra, use também os testes específicos para quando o checkout Magento 2 fica carregando.

O que evitar durante a recuperação

• apagar todos os logs antes de registrar a exceção;
• usar chmod 777 como correção permanente;
• editar tabelas diretamente sem diagnóstico e backup;
• desativar vários módulos ao mesmo tempo;
• atualizar dependências sem preservar o composer.lock;
• testar repetidamente pagamentos reais;
• exibir mensagens detalhadas de erro para visitantes.

Perguntas frequentes sobre erro 500 no Magento 2

Limpar o cache resolve o erro 500 no Magento 2?

Pode resolver quando o problema está restrito a dados de cache incompatíveis, mas não corrige falhas de PHP, permissões, dependências ou serviços indisponíveis. Leia os logs e preserve evidências antes da limpeza.

Onde ficam os logs do erro 500?

Os registros do Magento geralmente ficam em var/log/. Também é necessário consultar os logs do PHP-FPM, Nginx, Apache, contêiner ou serviço de hospedagem no mesmo horário da falha.

É seguro ativar o modo desenvolvedor em produção?

Não é uma boa prática usar o modo desenvolvedor para expor detalhes em uma loja pública. Reproduza a falha em homologação e mantenha informações técnicas e dados sensíveis fora da resposta enviada aos visitantes.

Quando restaurar um backup?

A restauração deve ser considerada quando houver corrupção ou mudança que não possa ser revertida com segurança. Antes disso, confirme a causa, a consistência do backup e o impacto sobre pedidos, clientes e integrações criados após a cópia.

Conclusão

O erro 500 no Magento 2 deve ser tratado como um sintoma, não como um diagnóstico. Delimitar a rota afetada, correlacionar horários e ler a primeira exceção relevante normalmente é mais seguro do que limpar caches, recompilar ou restaurar arquivos às cegas.

Se a loja continua indisponível ou o erro envolve várias camadas, uma análise técnica pode reduzir o tempo de recuperação e preservar dados importantes. A equipe do Suporte Magento pode ajudar a investigar a aplicação, as integrações e a infraestrutura com um plano controlado de correção.