A “tela branca” (white screen) no Magento 2 costuma aparecer do nada — após atualizar módulo/tema, mudar PHP, instalar extensão, mexer no checkout ou até por falta de recursos no servidor. O resultado é o pior possível: cliente não compra, e você não vê erro nenhum.
A boa notícia: na maioria dos casos dá para diagnosticar rápido seguindo uma ordem certa.
Objetivo deste guia: fazer você sair do escuro e chegar na causa (log/erro) para corrigir com segurança.
Principais causas da tela branca no Magento 2
1) Erro fatal de PHP (mas “escondido”)
Muitos servidores não exibem erros por padrão, então o Magento quebra e você só vê branco.
Gatilhos comuns:
- extensão recém-instalada
- incompatibilidade com versão do PHP
- conflito de tema/override
- update incompleto (deploy/compile)
2) Cache/geração de estáticos quebrados
Depois de deploy mal feito, o front pode ficar sem arquivos estáticos ou com cache inconsistente.
3) Permissões erradas
Se o Magento não consegue ler/gravar em pastas críticas, pode falhar sem mostrar nada no navegador.
4) Falta de memória/recursos (PHP memory / CPU)
Em compile, reindex e deploy, o servidor pode “morrer” e deixar o site instável.
5) Problemas em di:compile / dependências (Composer)
Dependências inconsistentes, autoload quebrado ou módulos com erro geram tela branca no admin e/ou front.
Diagnóstico rápido (em ordem) para sair da tela branca
1) Confira os logs do Magento (primeira coisa)
Comece por aqui, porque normalmente a causa já aparece.
var/log/system.logvar/log/exception.logvar/report/(quando habilitado)
Dica: se a tela branca acontecer só em uma página (ex.: checkout), procure no log o horário exato do erro.
2) Ative o modo desenvolvedor (para enxergar o erro)
Em ambiente de homologação/staging, use developer mode para exibir mensagens e acelerar o diagnóstico.
Em produção, o ideal é não deixar developer ligado o tempo todo — use temporariamente com cuidado e preferencialmente em janela de manutenção.
3) Verifique o error_log do servidor
Quando o Magento não registra, o erro pode estar no log do PHP/Apache/Nginx.
4) Desative o último módulo/tema alterado
Se a tela branca começou após instalar/atualizar algo, volte o último passo (rollback) e reexecute o deploy corretamente.
5) Refaça o “ciclo de deploy” completo
Quando o problema é cache/estáticos/compile, um ciclo completo costuma resolver:
- limpar cache
- regenerar estáticos
- compilar DI
- reindexar (se necessário)
Importante: execute o deploy do jeito correto para o seu cenário (produção vs. homologação).
Tela branca no Admin ou no Checkout: o que muda?
Tela branca no Admin
Geralmente é:
- erro em módulo do painel
- problema de permissões em
var/egenerated/ - conflito de UI component / requirejs
Tela branca no Checkout
Muito comum ser:
- conflito de extensões de pagamento/frete
- JS quebrado por minificação/merge
- CSP mal configurado (dependendo do stack)
- erro em regra de carrinho, imposto, CUPOM, etc.
Se a tela branca é “só no checkout”, trate como prioridade máxima: é perda direta de vendas.
Checklist rápido (copie e use)
- O problema começou após update/extensão/tema?
- Tem erro em
exception.log/system.log? - O
error_logdo servidor acusa fatal error? - As permissões das pastas
var/,pub/,generated/estão ok? - O deploy foi feito completo (cache + estáticos + compile)?
- O PHP/Composer estão compatíveis com sua versão do Magento 2?
Boas práticas para evitar tela branca no Magento 2
Tenha um staging (homologação) igual à produção
Testar update direto em produção é convite ao problema.
Monitore erros e quedas
Ferramentas de monitoramento ajudam a descobrir o erro antes do cliente.
Atualize com método, não no impulso
Atualizações em Magento exigem sequência e validação.
Segurança Magento 2026: checklist para sua loja
https://suportemagento.com.br/seguranca-magento-2026-checklist-para-sua-loja/
