Fixing 500 errors in Laravel — a battle-tested checklist

From storage permissions to queue workers, this is the exact order we run through when a Laravel app is down.

Comece pelo log

Uma página “500 Server Error” diz apenas que algo falhou. O motivo está nos logs. Veja primeiro o storage/logs/laravel.log (ou o arquivo diário, se você usa logs diários). Se ele estiver vazio, o erro aconteceu antes que o Laravel pudesse registrá-lo, então confira em seguida o log de erros do servidor web e o log de erros do PHP-FPM ou do LiteSpeed.

Não defina APP_DEBUG=true em um site em produção para ver o erro. Isso mostra stack traces, valores de ambiente e, às vezes, senhas a qualquer pessoa que abrir a página. Leia os logs em vez disso.

tail -n 100 storage/logs/laravel.log
# no entries? check the server logs, for example:
tail -n 100 /var/log/nginx/error.log

1. Permissões

O Laravel precisa conseguir gravar em storage e em bootstrap/cache. Depois de um upload por FTP ou de um deploy feito com outro usuário, essas pastas muitas vezes ficam com o dono errado. O log mostrará “Permission denied” ou “failed to open stream”. Dê ao usuário do servidor web permissão de escrita apenas nessas duas pastas — nunca torne o projeto inteiro gravável.

2. Ambiente e cache de configuração

Um valor ausente ou errado no .env é uma causa clássica: falta de APP_KEY (“No application encryption key has been specified”), senha do banco errada ou um driver de cache que não existe no servidor. Lembre-se de que, depois de php artisan config:cache, o Laravel não lê mais o .env em tempo de execução, e qualquer chamada a env() fora dos arquivos de configuração retorna null. Altere o .env e depois recrie o cache.

3. Dependências e autoload

“Class not found” logo após um deploy geralmente significa que a pasta vendor não foi atualizada ou que o autoloader está desatualizado. Rode composer install com --no-dev e --optimize-autoloader no servidor e confira se a versão do PHP e as extensões do servidor correspondem ao que o composer.lock exige.

4. Banco de dados e migrações

Um código novo que espera uma coluna que o banco ainda não tem gera erros SQL como “Unknown column” ou “Base table or view not found”. Rode as migrações pendentes com --force em produção. Verifique também se o banco de dados e o Redis estão acessíveis e não ficaram sem conexões.

5. Caches desatualizados e queue workers

Rotas, views e configurações em cache da versão anterior podem apontar para código que não existe mais. Limpe e recrie esses caches em todo deploy. Os queue workers são processos de longa duração: eles mantêm o código antigo na memória até serem reiniciados, então os jobs podem falhar com erros que já não correspondem ao seu código.

composer install --no-dev --optimize-autoloader
php artisan migrate --force
php artisan optimize:clear
php artisan config:cache && php artisan route:cache && php artisan view:cache
php artisan queue:restart

6. Memória, timeouts e serviços externos

Exportações grandes, processamento de imagens ou consultas sem limite podem ultrapassar o memory_limit ou o max_execution_time do PHP. Mova os trabalhos pesados para jobs na fila e processe os dados em partes. Chamadas a APIs externas devem sempre ter um timeout e uma alternativa, para que um provedor lento não derrube suas páginas. Observe a diferença entre os códigos: um 502 ou 504 geralmente aponta para o PHP-FPM ou para um timeout do proxy, não para uma exceção da aplicação.

Evite o próximo

Use um único script de deploy que sempre execute as mesmas etapas, na mesma ordem.
Adicione rastreamento de erros (por exemplo, Sentry ou Flare) para saber dos erros antes dos clientes.
Monitore a rota de saúde /up que o Laravel inclui, além de uma página que acesse o banco de dados.
Mantenha o ambiente de homologação o mais parecido possível com a produção: mesma versão do PHP, mesmas extensões e mesmos drivers de cache.