Erro 500 no Magento 2: descubra a causa antes de mexer na loja

O erro 500 no Magento 2 indica que o servidor não conseguiu concluir uma requisição, mas a página exibida ao visitante raramente revela a causa. A loja pode parar depois de uma atualização, instalação de módulo, alteração no PHP, deploy incompleto ou mudança na infraestrutura.

Por ser uma resposta genérica, tentar várias correções ao mesmo tempo costuma dificultar o diagnóstico. O caminho mais seguro é descobrir onde o erro acontece, consultar os registros corretos e relacionar o horário da falha com as últimas alterações realizadas.

O que significa o erro 500 no Magento 2?

O código HTTP 500 representa um erro interno do servidor. Ele informa que a requisição chegou ao ambiente, mas alguma camada não conseguiu processá-la normalmente. Essa camada pode ser o Magento, o PHP-FPM, o servidor web, uma extensão ou um serviço do qual a aplicação depende.

Na prática, o mesmo código pode aparecer em situações diferentes:

• todas as páginas da loja retornam erro;
• somente o painel administrativo fica indisponível;
• uma categoria, produto ou página específica falha;
• o erro aparece ao salvar configurações ou produtos;
• uma rota de API retorna HTTP 500;
• checkout ou pagamento falham em determinada etapa;
• o problema começa logo após um deploy.

Essa diferença é importante. Se apenas uma rota falha, é mais provável que o problema esteja em um módulo, controller, plugin ou dado específico. Quando o site inteiro cai, devem ser investigados PHP, arquivos gerados, dependências, permissões e infraestrutura.

Principais causas do erro 500 no Magento 2

Exceção em módulo ou customização

Plugins, observers, preferências e módulos de terceiros podem interromper uma requisição com uma exceção não tratada. Isso é comum depois de atualizar a plataforma, trocar o PHP ou instalar uma nova versão de extensão sem validar sua compatibilidade.

Quando a falha surgiu durante uma atualização, também vale investigar dependências bloqueadas ou incompatíveis. Veja como analisar um erro no Composer causado por módulo incompatível.

PHP incompatível ou sem recursos suficientes

Uma versão de PHP fora dos requisitos da edição instalada pode provocar erros de sintaxe, incompatibilidade de bibliotecas ou falhas em extensões. Limite de memória insuficiente e tempo máximo de execução também podem interromper operações pesadas, embora nem todo problema de lentidão resulte necessariamente em HTTP 500.

Confirme separadamente a versão usada no terminal e a versão atendida pelo PHP-FPM. Em alguns servidores, o comando php -v mostra uma versão diferente daquela usada pela loja no navegador.

Deploy incompleto e arquivos gerados inconsistentes

Interromper a instalação de dependências, a compilação de injeção de dependência ou a publicação de conteúdo estático pode deixar o ambiente inconsistente. O código novo passa a conviver com arquivos gerados anteriormente, causando classes ausentes, factories desatualizadas ou referências incompatíveis.

Esse cenário não deve ser resolvido apagando diretórios aleatoriamente em produção. Primeiro confirme o modo da aplicação, a estratégia de deploy e a possibilidade de restaurar a versão anterior.

Permissões ou proprietário incorretos

O usuário do PHP precisa conseguir acessar o código e escrever nos diretórios apropriados, como var, generated e pub/static, conforme a arquitetura do ambiente. Alterações de proprietário após upload, deploy executado como usuário inadequado ou montagem de volume com regras diferentes podem provocar falhas.

Evite usar chmod 777 como solução. Além de ampliar a exposição do servidor, isso mascara o problema real de proprietário, grupo ou política de execução.

Servidor web, PHP-FPM ou serviço externo

Configurações inválidas no Nginx ou Apache, workers indisponíveis, falha no PHP-FPM e regras incorretas de redirecionamento também podem gerar erro 500. Banco de dados, Redis e mecanismo de busca indisponíveis normalmente deixam rastros nos logs da aplicação ou dos respectivos serviços.

Se o problema estiver relacionado ao catálogo e aos resultados de pesquisa, use também o diagnóstico de falhas na busca do Magento para verificar motor de busca, comunicação e indexação.

Como diagnosticar o erro 500 no Magento 2

1. Delimite o alcance e o momento da falha

Registre a URL, o horário aproximado, a ação executada e o tipo de usuário afetado. Teste sem repetir pedidos ou cobranças. Em erros no checkout, uma nova tentativa pode criar operações duplicadas em integrações que já receberam a primeira solicitação.

Também confira o que mudou imediatamente antes da falha: pacote atualizado, configuração salva, módulo ativado, credencial alterada, certificado renovado ou deploy realizado.

2. Consulte os logs do Magento

A partir da raiz da instalação, os arquivos mais úteis costumam estar em var/log. Os nomes disponíveis dependem da configuração e da versão:

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

Procure registros no mesmo horário do erro. Identifique a primeira exceção relevante e não apenas os erros gerados em cascata. Nome de módulo, classe, arquivo, tabela ou serviço costuma indicar a camada que deve ser investigada.

3. Verifique logs do servidor e do PHP

Se não houver registro no Magento, a execução pode estar falhando antes de a aplicação conseguir gravar seus próprios logs. Consulte o log de erro do Nginx ou Apache, o journal do serviço e o log do PHP-FPM. Os caminhos e nomes variam entre distribuições e painéis de hospedagem.

Falhas como processo encerrado, configuração inválida, arquivo inacessível ou ausência de extensão do PHP podem aparecer somente nessa camada.

4. Confirme requisitos e estado da aplicação

Com acesso autorizado ao terminal, alguns comandos de leitura ajudam a reunir informações:

php -v
php bin/magento --version
php bin/magento maintenance:status
php bin/magento cache:status
php bin/magento indexer:status
composer check-platform-reqs

Se o próprio bin/magento falhar, a mensagem do terminal pode revelar dependência ausente, erro de bootstrap, módulo incompatível ou problema de leitura. Não execute atualização geral do Composer como tentativa de reparo, pois ela pode modificar vários pacotes e ampliar a indisponibilidade.

5. Reproduza em staging

Quando a causa não é evidente, reproduza a versão do código e as configurações relevantes em staging, com dados devidamente protegidos. Nesse ambiente é possível testar a desativação de um módulo suspeito, recompilar dependências e validar mudanças sem transformar a loja em produção em laboratório.

Se o erro começou durante um upgrade, revise também o plano da versão desejada. Uma atualização deve considerar checkout, tema, integrações, infraestrutura e extensões, como explicado no guia sobre planejamento de atualização do Magento.

Como corrigir sem piorar a indisponibilidade

A correção depende da evidência encontrada. Não existe um único comando capaz de resolver todo erro 500. Depois de identificar a origem, o procedimento pode envolver:

• restaurar o código estável do deploy anterior;
• corrigir a compatibilidade de um módulo;
• instalar uma extensão do PHP exigida pela aplicação;
• ajustar proprietário e permissões de forma restritiva;
• refazer o deploy e a compilação em uma janela controlada;
• corrigir configuração do servidor web ou PHP-FPM;
• restabelecer a comunicação com banco, Redis ou busca;
• corrigir dados ou customizações relacionados à rota afetada.

Antes de qualquer alteração em produção, preserve logs, confirme backups e defina uma possibilidade de rollback. Após a correção, teste home, categorias, produtos, busca, login, carrinho, checkout, painel administrativo, APIs e tarefas agendadas relevantes.

O que não fazer diante de um erro 500

• não habilite exibição pública de erros com caminhos e detalhes internos;
• não aplique permissão 777 em toda a instalação;
• não apague vendor, generated ou caches sem entender o deploy;
• não rode composer update diretamente em produção por tentativa;
• não desative vários módulos simultaneamente sem registrar as mudanças;
• não restaure banco ou arquivos sem avaliar pedidos realizados após o backup.

Essas medidas podem esconder a exceção original, criar incompatibilidades e aumentar o tempo necessário para recuperar a operação.

Perguntas frequentes

Limpar o cache resolve o erro 500 no Magento 2?

Pode resolver quando o erro está ligado a conteúdo de cache incompatível após uma mudança, mas não corrige módulo quebrado, dependência ausente, permissão incorreta ou falha de infraestrutura. Consulte os logs antes de tratar a limpeza como solução definitiva.

Como descobrir qual módulo está causando o erro?

Relacione o horário da falha com exception.log, system.log e logs do PHP. O stack trace pode apontar o namespace ou a classe responsável. A confirmação por desativação deve ser feita preferencialmente em staging.

Por que o Magento mostra apenas uma página genérica?

Em produção, detalhes técnicos não devem ser exibidos aos visitantes. Isso reduz a exposição de caminhos, classes e informações internas. O diagnóstico deve ser realizado pelos logs e pelo monitoramento do servidor.

É seguro corrigir o erro diretamente em produção?

Correções emergenciais podem ser necessárias, mas devem ter backup, registro das alterações, janela controlada e plano de rollback. Mudanças de dependências, módulos ou infraestrutura devem ser validadas em staging sempre que possível.

Conclusão

O erro 500 no Magento 2 só pode ser corrigido com segurança quando a equipe identifica a camada responsável. Logs, horário da ocorrência, últimas mudanças e reprodução controlada são mais úteis do que limpar tudo ou executar comandos por tentativa.

Se a loja continua indisponível ou a exceção envolve checkout, deploy, PHP ou infraestrutura, uma análise técnica pode reduzir o risco de novas falhas. A equipe do SuporteMagento.com.br pode ajudar a localizar a origem do problema e planejar a correção com menor impacto para a operação.