Erro 500 no Magento 2? Faça estes 9 testes para encontrar a causa real

O erro 500 no Magento 2 informa que o servidor não conseguiu concluir a requisição, mas não revela sozinho o componente responsável. A falha pode surgir depois de um deploy, instalação de módulo, atualização, mudança no PHP ou até durante uma operação específica no catálogo, checkout ou painel.

Reiniciar serviços e limpar todos os caches pode fazer o sintoma desaparecer temporariamente, além de eliminar pistas importantes. O diagnóstico mais seguro começa pela URL afetada, pelo horário exato da ocorrência e pelos registros produzidos em cada camada. Faça os testes abaixo antes de alterar a loja.

O que significa o erro 500 no Magento 2?

O status HTTP 500 representa uma falha interna que impediu a aplicação de entregar uma resposta válida. Em uma loja Magento, essa resposta pode ser gerada pelo servidor web, PHP-FPM, aplicação, extensão, tema, integração ou serviço intermediário.

Primeiro, delimite o alcance do problema:

• todas as páginas apresentam erro ou somente uma rota;
• a vitrine funciona, mas o painel administrativo falha;
• o erro ocorre apenas ao salvar produtos, gerar pedidos ou abrir o checkout;
• clientes convidados são afetados, mas clientes autenticados não;
• a falha começou imediatamente após uma mudança identificável.

Essa classificação reduz o campo de investigação. Se somente uma página de produto falha, por exemplo, é menos provável que todo o PHP-FPM esteja indisponível.

9 testes para diagnosticar o erro 500 no Magento 2

1. Confirme o status HTTP e preserve a resposta

Abra as ferramentas de desenvolvedor do navegador, acesse a guia de rede e reproduza a falha. Verifique qual requisição recebeu o status 500, pois a página pode carregar normalmente enquanto uma chamada REST, GraphQL ou AJAX é interrompida.

Também é possível consultar uma URL pública pelo terminal:

curl -I https://exemplo.com.br/url-afetada

Registre horário, URL, método HTTP, usuário utilizado e ação executada. Evite publicar cookies, tokens, dados pessoais ou conteúdo de pedidos ao compartilhar o diagnóstico.

2. Consulte primeiro os logs do Magento

Na raiz da instalação, examine os arquivos disponíveis em var/log. Os nomes e o conteúdo podem variar conforme a versão, as extensões e a configuração de logging.

ls -lah var/log
tail -n 150 var/log/system.log
tail -n 150 var/log/exception.log

Procure registros no mesmo instante em que a requisição falhou. A última mensagem nem sempre é a causa: leia a exceção completa, incluindo a primeira mensagem, o arquivo envolvido e a cadeia de chamadas.

Verifique também var/report quando houver um identificador de relatório exibido pela página de erro. Não exponha esse conteúdo publicamente, pois ele pode revelar caminhos internos e detalhes da aplicação.

3. Cruze o evento com Nginx, Apache e PHP-FPM

Se o Magento não registrou a exceção, a requisição pode ter falhado antes de chegar corretamente à aplicação. Consulte os logs de erro do servidor web e do PHP-FPM pelo painel da hospedagem, observabilidade centralizada ou caminhos definidos na infraestrutura.

Mensagens como Allowed memory size exhausted, Maximum execution time exceeded, Primary script unknown e falhas de conexão com o upstream apontam para investigações diferentes. Não aumente memória ou tempo de execução sem entender qual processo está consumindo os recursos; isso pode apenas prolongar uma operação defeituosa.

4. Verifique se a falha começou após deploy ou instalação

Compare o horário do primeiro erro com os últimos commits, pacotes instalados, patches, alterações de tema e mudanças de infraestrutura. Confirme o estado do projeto:

git status
git log -5 --oneline
composer validate
php bin/magento --version

Não apague o composer.lock nem execute uma atualização geral para tentar resolver um pacote isolado. Se houver mensagens sobre dependências, siga um processo controlado para tratar o erro do Composer no Magento 2.

5. Confirme a compatibilidade do PHP e das extensões

Uma troca de versão do PHP pode introduzir incompatibilidades no código ou deixar extensões obrigatórias indisponíveis. Compare o PHP usado no terminal com aquele executado pelo PHP-FPM, pois eles podem carregar versões e arquivos de configuração diferentes.

php -v
php --ini
php -m

Consulte o log do FPM para identificar erros fatais, classes ausentes e funções indisponíveis. A solução deve considerar os requisitos da versão efetivamente instalada do Magento e de seus módulos, sem habilitar extensões aleatoriamente.

6. Investigue classes geradas, injeção de dependência e autoload

Erros como Class not found, argumentos incompatíveis, proxies ausentes ou interceptors inválidos podem aparecer quando o código implantado não corresponde aos artefatos gerados. Isso acontece, por exemplo, em deploys incompletos ou quando nós diferentes recebem versões distintas.

Confira se o release foi construído por inteiro e distribuído para todos os servidores. Comandos de compilação devem ser testados no mesmo processo usado pela equipe e executados em homologação ou em uma janela controlada, nunca como tentativa improvisada durante o tráfego normal:

php bin/magento setup:di:compile

Se o erro apareceu junto com uma página sem formatação, investigue separadamente por que CSS e JavaScript não carregam após o deploy. Arquivos estáticos ausentes costumam gerar respostas 404, mas uma customização de frontend também pode acionar requisições que terminam em 500.

7. Valide permissões sem aplicar 777

O usuário do servidor web precisa acessar os arquivos da aplicação e gravar apenas nos diretórios previstos pela arquitetura do projeto. Uma falha após migração, restauração de backup ou deploy pode estar relacionada a proprietário e grupo incorretos.

Examine os diretórios citados na exceção e compare suas permissões com as de um release funcional. Não use chmod -R 777: além de ampliar a superfície de risco, o comando mascara a configuração inadequada de usuários, grupos e processo de deploy.

8. Teste banco, cache, sessões e serviços externos

Nem todo erro 500 nasce no código PHP. Indisponibilidade, autenticação inválida ou demora excessiva no banco de dados, Redis, mecanismo de busca, filas e APIs externas pode terminar como uma exceção interna.

Verifique a saúde dos serviços pela ferramenta de monitoramento da infraestrutura e procure no log expressões como connection refused, timeout, falha de DNS ou limite de conexões. Se o erro ocorre apenas ao pesquisar, calcular pagamento ou enviar dados ao ERP, concentre o teste na dependência acionada por aquela operação.

9. Separe erro de indexação, cache e processamento assíncrono

Consulte o estado da aplicação antes de reindexar ou limpar caches:

php bin/magento cache:status
php bin/magento indexer:status
php bin/magento cron:run --group default

O último comando deve ser usado apenas quando fizer sentido no fluxo operacional, pois pode iniciar tarefas pendentes. Se houver estados Processing ou Reindex Required, veja como tratar indexadores Magento 2 travados sem reprocessar tudo por impulso.

A limpeza de cache é adequada quando existem evidências de configuração ou conteúdo obsoleto. Ela não corrige erro fatal, falta de memória, classe inexistente ou serviço indisponível.

O que evitar durante a correção

• ativar o modo developer em produção para exibir exceções aos visitantes;
• apagar vendor, composer.lock ou diretórios inteiros sem backup e plano de reconstrução;
• alterar permissões recursivamente sem conhecer o usuário da aplicação;
• reiniciar todos os serviços antes de coletar logs e métricas;
• executar compilação, upgrade ou reindexação completa durante o pico;
• testar correções diretamente no checkout de produção.

Depois de identificar a causa, reproduza a correção em homologação, valide vitrine, busca, login, carrinho, frete, pagamento e painel, e prepare um caminho de rollback.

Conclusão: corrija o erro 500 no Magento 2 pela evidência

O erro 500 no Magento 2 deve ser tratado como um sintoma, não como um diagnóstico. A combinação da requisição afetada, horário preciso, logs da aplicação, servidor web e PHP normalmente indica em qual camada a execução foi interrompida.

Se a loja continua indisponível ou a equipe não consegue isolar a origem, um diagnóstico técnico pode reduzir tentativas de risco. A equipe do SuporteMagento.com.br pode auxiliar na análise da aplicação, extensões e infraestrutura.

Perguntas frequentes sobre erro 500 no Magento 2

Limpar o cache resolve o erro 500 no Magento 2?

Somente quando a falha está ligada a configuração ou conteúdo obsoleto em cache. Erros fatais de PHP, classes ausentes, permissões e serviços indisponíveis exigem a correção da causa.

Onde ficam os logs de erro do Magento 2?

Os registros da aplicação costumam estar em var/log, enquanto relatórios podem aparecer em var/report. Também é necessário consultar os logs do servidor web e do PHP-FPM.

É seguro ativar o modo developer para encontrar a falha?

Em ambiente de desenvolvimento ou homologação, ele pode ampliar as informações disponíveis. Em produção, a exibição de exceções aos visitantes pode expor detalhes internos e não deve ser usada como solução de diagnóstico.

Por que o erro 500 aparece apenas em uma página?

Aquela rota pode acionar um módulo, bloco, produto, integração ou consulta específica. Compare os logs gerados ao abrir a URL afetada com uma página que continua funcionando.