Erro 500 no Magento 2? Encontre a causa em 9 testes sem apagar as pistas

Erro 500 no Magento 2 significa que o servidor não conseguiu concluir a solicitação, mas a página exibida ao visitante raramente revela a causa. O defeito pode estar no PHP, no servidor web, em permissões, dependências, módulos, serviços externos ou em um deploy incompleto.

Antes de limpar caches, reiniciar todos os serviços ou restaurar um backup, registre a URL, o horário, o usuário afetado e a última alteração realizada. Os nove testes abaixo ajudam a identificar a camada responsável sem apagar as evidências necessárias para uma correção segura.

Erro 500 no Magento 2: delimite o alcance primeiro

Comece verificando se a falha atinge toda a aplicação ou apenas uma operação. Teste, de forma controlada, a página inicial, um produto, uma categoria, o carrinho, o checkout e o Admin. Se houver APIs ou aplicações headless, verifique também uma chamada conhecida.

Os resultados iniciais ajudam a definir a prioridade:

• Toda a loja retorna 500: investigue deploy, PHP, servidor web, permissões e indisponibilidade de dependências.
• Apenas uma página falha: procure dados inconsistentes, customizações e blocos executados naquela rota.
• Somente o Admin apresenta erro: avalie módulos administrativos, ACL, sessão e customizações de painel.
• Apenas checkout ou API falha: examine integrações, payloads, autenticação e exceções específicas do fluxo.
• O problema é intermitente: considere falta de recursos, processos concorrentes, timeout e dependências instáveis.

1. Preserve o contexto antes de tentar corrigir

Anote o horário com fuso, URL completa, método HTTP, código de resposta, navegador, conta utilizada e identificador do pedido ou carrinho, quando aplicável. Registre também deploys, atualizações de módulos e mudanças de configuração realizadas perto do início da falha.

Evite começar com uma limpeza geral. Cache, sessão e logs podem conter pistas importantes, especialmente quando o erro ocorre apenas com determinado cliente, produto ou método de pagamento. Se a loja começou a falhar depois de uma instalação, consulte também o roteiro para identificar um pacote bloqueando o Composer no Magento 2.

2. Confirme o código HTTP e quem o gerou

Uma tela branca ou mensagem genérica não confirma sozinha um erro 500. Use as ferramentas de rede do navegador ou uma requisição de cabeçalho para observar a resposta:

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

Execute o teste somente em um endereço sob sua administração. Compare os cabeçalhos e o conteúdo retornado. Uma resposta produzida pelo proxy, CDN ou balanceador pode ter aparência semelhante à resposta da aplicação, embora a origem do problema esteja em outra camada.

Se possível, compare o acesso público com um teste interno controlado. Não contorne controles de segurança nem exponha a origem da aplicação na internet apenas para realizar o diagnóstico.

3. Cruze os logs pelo mesmo horário

Consulte primeiro os registros do Magento em var/log/, especialmente exception.log, system.log e arquivos adicionais criados por módulos. Dependendo da configuração, relatórios também podem aparecer em var/report/.

Depois, examine os logs do servidor web, do PHP-FPM e da infraestrutura. O caminho exato varia conforme sistema operacional, painel e arquitetura. Pesquise pelo horário e pela rota, não apenas pela palavra “error”. A exceção principal pode aparecer algumas linhas antes das mensagens geradas em sequência.

Não publique logs completos em chamados ou canais abertos. Eles podem conter caminhos internos, endereços, tokens, dados de sessão e informações de integrações.

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

No diretório do Magento, com o usuário correto da aplicação, consulte o modo atual:

php bin/magento maintenance:status

O modo de manutenção normalmente produz uma resposta diferente, mas proxies ou páginas personalizadas podem mascarar o comportamento. Verifique ainda se o espaço em disco acabou, se o sistema de arquivos ficou somente para leitura e se os diretórios necessários continuam acessíveis pelo processo do PHP.

Não altere permissões recursivamente sem entender o proprietário e o grupo esperados. Comandos amplos podem tornar arquivos sensíveis graváveis ou quebrar o próximo deploy.

5. Compare o PHP da linha de comando com o PHP da web

Confira a versão e os módulos disponíveis no terminal:

php -v
php -m
php --ini

Esses resultados representam o PHP da linha de comando. O servidor web pode usar outra versão, outro arquivo php.ini, extensões diferentes ou limites próprios de memória e tempo. Essa divergência explica situações em que comandos do Magento funcionam, mas a vitrine retorna erro 500.

Nos registros do PHP-FPM, procure falhas fatais, falta de memória, arquivos ausentes e encerramentos de processos. Aumentar limites sem identificar o consumo pode apenas adiar uma nova falha.

6. Valide arquivos gerados e dependências sem atualizar pacotes

Confirme se vendor/ está presente e coerente com o composer.lock. Para verificar a integridade básica das dependências declaradas, use:

composer validate --no-check-publish
composer check-platform-reqs

Esses comandos não substituem a análise do deploy, mas ajudam a detectar requisitos de plataforma ausentes e problemas de definição. Evite executar composer update como tentativa genérica, pois isso recalcula versões e pode ampliar o incidente.

Se o erro começou depois de uma compilação ou publicação de estáticos, compare o procedimento utilizado com o pipeline aprovado. Não remova diretórios gerados indiscriminadamente em produção enquanto houver requisições ativas.

7. Isole módulo, tema ou customização alterada

Liste o que mudou imediatamente antes do incidente: módulo novo, atualização, plugin, preferência, observer, tema ou configuração de escopo. Procure no stack trace a primeira classe pertencente a uma customização, sem assumir que o último arquivo citado é necessariamente o responsável.

A desativação de um módulo pode exigir atualização de esquema, compilação e testes de dependência. Portanto, não desative componentes diretamente em produção apenas para “ver se volta”. Reproduza o problema em homologação com cópia sanitizada da configuração e um plano de retorno.

8. Teste banco, cache, sessões e busca separadamente

Uma dependência indisponível pode terminar como erro 500 dentro da aplicação. Verifique conectividade, latência e erros de autenticação do banco de dados, mecanismo de busca, armazenamento de cache, sessões, filas e serviços consumidos pela rota.

Faça testes por componente. Reiniciar tudo simultaneamente impede saber qual serviço causou a recuperação. Se houver mensagens relacionadas a cache ou sessão, siga um diagnóstico específico para falhas de Redis no Magento 2 antes de esvaziar bancos ou derrubar conexões.

Quando apenas páginas de catálogo falham, observe também índices e consultas de busca. Uma reindexação interrompida merece investigação própria; veja como diagnosticar quando a reindexação do Magento 2 falha ou não termina.

9. Reproduza a falha e valide a correção completa

Depois de encontrar uma hipótese, reproduza o erro em condições controladas. Altere apenas uma variável por vez e registre o resultado. Uma correção deve eliminar a exceção original sem criar regressões em login, catálogo, carrinho, checkout, Admin, cron e integrações.

Monitore os logs após a intervenção e repita a rota com diferentes perfis de acesso. Se o erro era intermitente, uma única resposta bem-sucedida não basta: valide durante um período compatível com a frequência anterior da falha.

O que evitar durante um erro 500

• Ativar exibição pública de erros e stack traces em produção.
• Executar atualizações gerais do Composer durante o incidente.
• Apagar logs, relatórios, sessões e caches antes de preservar evidências.
• Aplicar permissões amplas e recursivas como solução temporária.
• Reiniciar todos os serviços ao mesmo tempo sem registrar o estado anterior.
• Restaurar banco ou código sem avaliar pedidos e alterações posteriores ao backup.

Perguntas frequentes sobre erro 500 no Magento 2

Limpar o cache resolve o erro 500 no Magento 2?

Pode resolver um artefato de cache incompatível, mas não corrige falhas de PHP, dependências ausentes, permissões ou indisponibilidade de serviços. Preserve logs e confirme a causa antes de limpar tudo.

Onde ficam os logs relacionados ao erro?

Os registros da aplicação costumam ficar em var/log/, com possíveis relatórios em var/report/. Também devem ser consultados os logs do servidor web, PHP-FPM, proxy e serviços de infraestrutura.

Devo ativar o modo developer em produção?

Não como tentativa genérica. O modo developer pode expor informações sensíveis e alterar o comportamento operacional. Reproduza a falha em homologação e mantenha detalhes técnicos fora da resposta pública.

Como saber se o problema começou no último deploy?

Compare o horário da primeira falha com o início e o fim do deploy, examine os arquivos alterados e valide dependências, compilação e publicação de estáticos. Correlação de horário é uma pista, não uma prova isolada.

Conclusão

O erro 500 no Magento 2 deve ser tratado como um sintoma que exige correlação entre rota, horário, logs, código e infraestrutura. Preservar evidências e testar uma camada por vez reduz o risco de recuperar a página temporariamente sem corrigir a origem.

Se a falha afeta vendas ou reaparece sem uma causa clara, uma análise técnica pode organizar as evidências e definir a correção com menor impacto. A equipe do SuporteMagento.com.br pode ajudar no diagnóstico da aplicação e de suas dependências.