Erro 500 no Magento 2? Encontre a causa em 10 testes sem apagar evidências

O erro 500 no Magento 2 informa que o servidor não conseguiu concluir uma requisição, mas não revela sozinho onde está a falha. A causa pode estar no PHP, no servidor web, em uma extensão, no tema, nas permissões, no armazenamento ou em uma implantação incompleta.

Antes de limpar caches, restaurar um backup ou reiniciar todos os serviços, preserve os registros e delimite o impacto. Os dez testes abaixo ajudam a encontrar a origem do erro sem destruir evidências importantes para o diagnóstico.

Erro 500 no Magento 2: o que esse código realmente indica?

O código HTTP 500 representa uma falha interna durante o processamento da solicitação. Em uma loja Magento, ele pode ser devolvido diretamente pelo servidor web, pelo PHP-FPM, pela aplicação ou por uma camada intermediária da infraestrutura.

Isso significa que duas páginas visualmente iguais podem ter causas diferentes. Um erro restrito ao checkout pode envolver customizações, pagamento ou cálculo de totais. Se toda a loja e o painel falham, a investigação deve considerar indisponibilidade do PHP, permissões, recursos do servidor e problemas gerais no código.

1. Descubra exatamente onde o erro acontece

Registre a URL, o horário, a loja ou store view, o navegador e a ação executada. Teste separadamente:

• página inicial e páginas de produto;
• carrinho e checkout;
• painel administrativo;
• requisições REST ou GraphQL envolvidas;
• tarefas executadas pelo terminal ou cron.

Verifique também a resposta sem depender da renderização do navegador:

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

Não faça testes repetitivos no checkout de produção. Uma única reprodução, com horário anotado, normalmente é suficiente para correlacionar a requisição com os logs.

2. Confirme qual camada devolve o status 500

Abra as ferramentas de desenvolvedor do navegador e consulte a aba de rede. Identifique a requisição que falhou, seu método, o código HTTP e o momento da resposta. Em páginas dinâmicas, o HTML principal pode carregar normalmente enquanto uma chamada AJAX recebe o erro 500.

Compare, quando possível, o acesso pelo domínio público com uma consulta interna controlada. Cabeçalhos e tempos de resposta podem ajudar a diferenciar falhas no proxy, servidor web ou backend PHP. Não desative CDN, proxy ou firewall em produção apenas para testar; qualquer mudança de rota deve ser planejada pela equipe responsável pela infraestrutura.

3. Consulte primeiro os logs do Magento

Examine os arquivos em var/log/, principalmente os registros gerados no horário exato da falha. Os nomes disponíveis variam conforme a configuração e as extensões instaladas, mas normalmente vale verificar:

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

Procure exceções, nomes de classes, arquivos ausentes, falhas de conexão e mensagens iniciadas no momento do teste. Leia a cadeia completa da exceção: o último arquivo citado nem sempre é o componente que originou o problema.

Logs podem conter caminhos internos, dados de integrações e outras informações sensíveis. Evite publicá-los integralmente em chamados ou ferramentas abertas.

4. Verifique os relatórios de erro da aplicação

Dependendo do modo e da configuração da loja, a resposta pode apresentar um identificador de relatório em vez dos detalhes da exceção. Use esse identificador para localizar o arquivo correspondente no diretório var/report/.

ls -lt var/report/ | head

Não ative o modo desenvolvedor em produção para exibir erros aos visitantes. Além de afetar o comportamento e o desempenho da aplicação, essa alteração pode expor caminhos, classes e detalhes técnicos. Reproduza o problema em homologação quando for necessário obter uma mensagem mais completa.

5. Correlacione o horário com Nginx, Apache e PHP-FPM

Se os logs do Magento não registraram a falha, ela pode ter ocorrido antes de a aplicação concluir sua inicialização. Consulte os registros do servidor web e do PHP-FPM referentes ao mesmo minuto.

Mensagens sobre limite de memória, tempo máximo, processo encerrado, arquivo inexistente ou erro de sintaxe ajudam a reduzir o campo de busca. Os caminhos dos logs dependem da distribuição, do painel de hospedagem e da configuração da infraestrutura; por isso, confirme-os com o administrador do servidor.

Evite aumentar memória e tempo de execução indiscriminadamente. Um limite atingido pode ser consequência de consulta ineficiente, recursão ou incompatibilidade de código, e não apenas de uma configuração pequena.

6. Confira espaço em disco, inodes e memória

O Magento, o PHP e os serviços associados precisam gravar sessões, logs, caches e arquivos temporários. Falta de espaço ou de inodes pode impedir essas operações e provocar falhas aparentemente aleatórias.

df -h
df -i
free -h

Também verifique se houve encerramento de processos por pressão de memória. Se o disco estiver cheio, preserve os registros necessários antes de remover arquivos. Não apague recursivamente diretórios que você não identificou, especialmente sessões, uploads, backups e dados persistentes.

7. Revise o último deploy e as dependências do Composer

Se o erro começou após uma implantação, compare a alteração com o horário da primeira ocorrência. Confirme se código e composer.lock pertencem ao mesmo release, se a instalação de dependências terminou e se os pacotes atendem ao PHP disponível:

php -v
composer check-platform-reqs
bin/magento deploy:mode:show

Quando a atualização falha por dependências incompatíveis, use um diagnóstico direcionado em vez de apagar o arquivo de bloqueio. Veja também como investigar um conflito no Composer do Magento 2.

Não execute composer update diretamente em produção para tentar corrigir um erro 500. Esse comando pode alterar várias dependências e tornar o estado da aplicação ainda mais difícil de reproduzir.

8. Valide arquivos gerados, cache e permissões

Uma implantação incompleta pode deixar código gerado incompatível com o release atual. Antes de remover qualquer diretório, confirme o modo da aplicação, o usuário que executou o deploy e as permissões de leitura e gravação.

Limpar cache não corrige automaticamente classes ausentes, permissões incorretas ou compilação quebrada. Além disso, uma limpeza ampla pode aumentar a carga e eliminar pistas temporárias. Em homologação, reproduza o processo completo de instalação de dependências, compilação e conteúdo estático usando o mesmo código da produção.

Não aplique permissões globais como 777. O servidor web e o usuário de implantação devem seguir uma estratégia coerente de propriedade e grupos, limitada aos diretórios que realmente precisam de escrita.

9. Teste serviços externos sem culpar o frontend

Banco de dados, mecanismo de busca, Redis e integrações podem interromper uma requisição, mas o impacto depende da operação. Uma falha na busca pode atingir categorias e resultados; indisponibilidade do banco tende a ter alcance maior; uma integração síncrona pode quebrar somente uma etapa específica.

Consulte a saúde dos serviços pelos mecanismos aprovados na infraestrutura e procure erros de conexão nos logs. Se o problema estiver relacionado a sessões e resultar em perda do carrinho, siga também os testes para quando o carrinho do Magento 2 esvazia sozinho.

Evite reiniciar todos os componentes simultaneamente. Além de interromper usuários ativos, isso pode apagar a condição que permitiria identificar qual serviço falhou.

10. Faça uma recuperação controlada e valide a compra completa

Depois de identificar a causa provável, reproduza a correção em homologação. Se o incidente começou após um deploy, um rollback para um artefato conhecido pode ser mais seguro do que editar arquivos diretamente no servidor, desde que banco de dados e código permaneçam compatíveis.

Após a intervenção, não valide apenas a página que apresentava o erro. Teste navegação, login, produto, carrinho, checkout, pagamento, frete, painel, APIs e tarefas agendadas relevantes. Caso a falha afete especificamente a entrega, consulte as verificações para frete ausente no checkout Magento 2.

Registre a causa, a correção, os arquivos ou serviços alterados e os testes realizados. Esse histórico reduz o tempo de resposta se o incidente voltar a ocorrer.

O que não fazer diante de um erro 500

• Não ativar mensagens detalhadas de erro para visitantes.
• Não apagar composer.lock para forçar uma atualização.
• Não conceder permissão 777 em toda a instalação.
• Não limpar logs antes de preservar o período do incidente.
• Não reiniciar todos os serviços sem uma hipótese verificável.
• Não restaurar banco e arquivos sem avaliar compatibilidade e perda de pedidos.

Perguntas frequentes sobre erro 500 no Magento 2

Limpar o cache resolve o erro 500?

Pode ajudar quando o erro está relacionado a dados de cache incompatíveis, mas não corrige problemas de PHP, permissões, dependências, falta de recursos ou serviços indisponíveis. Consulte os logs antes de fazer uma limpeza ampla.

Posso ativar o modo desenvolvedor em produção?

Não é recomendado. O modo desenvolvedor pode expor informações técnicas e alterar o comportamento da aplicação. A investigação detalhada deve ser reproduzida em um ambiente protegido de homologação.

Como saber se o erro está em um módulo?

Correlacione o início da falha com o deploy e examine a cadeia completa da exceção. O nome de um módulo no log é uma pista, não uma confirmação. Faça a validação com a mesma versão do código em homologação antes de desativar componentes.

Devo restaurar o backup imediatamente?

Somente depois de avaliar a causa, a compatibilidade entre código e banco e o risco de perder pedidos ou alterações. Quando disponível, o rollback de um artefato conhecido costuma ser mais controlável do que uma restauração completa improvisada.

Conclusão

O erro 500 no Magento 2 deve ser tratado como um diagnóstico por camadas: primeiro delimite a página afetada, depois correlacione os logs e só então altere aplicação ou infraestrutura. Preservar evidências evita tentativas aleatórias e ajuda a corrigir a causa, não apenas o sintoma.

Se a loja continua indisponível ou o erro afeta compras, pagamentos e integrações, uma análise técnica do ambiente pode acelerar a recuperação. A equipe do SuporteMagento.com.br pode auxiliar no diagnóstico e na validação da correção.