O erro 500 em PHP é um dos problemas mais assustadores para quem administra sites, sistemas e APIs. Muitas vezes ele aparece como uma tela branca, uma mensagem genérica de erro interno ou uma resposta vazia no navegador. O problema é que o erro 500 não mostra automaticamente a causa real da falha.

Esse tipo de erro indica que algo deu errado no servidor, mas pode ter várias origens: erro de sintaxe no PHP, falha de conexão com banco, permissão incorreta em arquivos, problema no .htaccess, limite de memória, extensão ausente, erro fatal ou exception não tratada.

Neste artigo, você vai aprender como descobrir a causa do erro 500 em PHP usando logs do Apache, Nginx e PHP, além de técnicas como error_log, try/catch, ativação temporária de erros e boas práticas para ambiente de produção.

O que significa erro 500 em PHP?

O erro 500 Internal Server Error significa que o servidor encontrou uma falha interna ao processar a requisição. Em aplicações PHP, esse erro pode acontecer antes mesmo de qualquer HTML ou JSON ser enviado para o navegador.

Diferente de erros como 404 Not Found, que indicam uma página inexistente, o erro 500 aponta para uma falha no processamento da aplicação ou na configuração do servidor.

Algumas causas comuns são:

• Erro de sintaxe no PHP;
• Arquivo PHP com permissão incorreta;
• Erro no .htaccess;
• Falha na conexão com MySQL;
• Exception não tratada;
• Limite de memória excedido;
• Tempo máximo de execução atingido;
• Função ou extensão PHP ausente;
• Caminho de arquivo incorreto em require ou include;
• Erro ao enviar headers ou resposta JSON.

Por que o erro 500 não mostra detalhes?

Em servidores configurados corretamente para produção, os detalhes dos erros PHP geralmente ficam ocultos do usuário. Isso é importante por segurança, porque mensagens internas podem revelar caminhos de arquivos, nomes de tabelas, dados de conexão ou trechos do código.

Por isso, quando ocorre uma falha, o navegador pode mostrar apenas:

500 Internal Server Error

Ou uma mensagem genérica como:

Erro interno no servidor.

A mensagem real normalmente estará em algum arquivo de log.

Primeiro passo: verificar o log de erros

O log é o local onde o servidor registra informações sobre falhas, avisos e problemas internos. Para corrigir erro 500, você precisa encontrar a mensagem exata registrada no log.

Dependendo do ambiente, o erro pode aparecer em:

• Log do Apache;
• Log do Nginx;
• Log do PHP-FPM;
• Log configurado no php.ini;
• Log personalizado da aplicação;
• Painel da hospedagem, como cPanel, Plesk ou DirectAdmin.

Onde ficam os logs do Apache?

Em servidores Linux com Apache, os logs costumam ficar em caminhos como:

/var/log/apache2/error.log

Em algumas distribuições, também pode ser:

/var/log/httpd/error_log

Para acompanhar o log em tempo real via terminal:

tail -f /var/log/apache2/error.log

Depois de rodar o comando, acesse novamente a página que está dando erro 500. O log deve mostrar a mensagem real do erro.

Onde ficam os logs do Nginx?

Em servidores com Nginx, o log de erro geralmente fica em:

/var/log/nginx/error.log

Para acompanhar em tempo real:

tail -f /var/log/nginx/error.log

Se você usa Nginx com PHP-FPM, pode ser necessário verificar também o log do PHP-FPM.

Onde ficam os logs do PHP-FPM?

O caminho pode variar conforme a versão do PHP e a distribuição do servidor.

Exemplos comuns:

/var/log/php8.2-fpm.log
/var/log/php8.3-fpm.log
/var/log/php8.4-fpm.log

Também pode existir uma pasta específica:

/var/log/php-fpm/error.log

Se o erro 500 acontece em ambiente Nginx + PHP-FPM, conferir esse log é essencial.

Como localizar o arquivo de log usado pelo PHP

Você pode verificar a configuração do PHP usando um arquivo temporário com phpinfo.

<?php
phpinfo();

Salve como info.php, acesse pelo navegador e procure por:

• error_log
• display_errors
• log_errors
• Loaded Configuration File

Ativando log de erros no PHP

No php.ini, as configurações mais importantes são:

log_errors = On
error_log = /var/log/php_errors.log
display_errors = Off
display_startup_errors = Off
error_reporting = E_ALL

Em produção, o ideal é manter display_errors como Off e salvar os detalhes no log.

Após alterar o php.ini, reinicie o serviço do Apache ou PHP-FPM.

Exemplo com Apache:

sudo systemctl restart apache2

Exemplo com PHP-FPM:

sudo systemctl restart php8.3-fpm

Como ativar erros temporariamente no desenvolvimento

Em ambiente de desenvolvimento, você pode exibir erros diretamente na tela para facilitar o diagnóstico.

<?php

ini_set('display_errors', 1);
ini_set('display_startup_errors', 1);
error_reporting(E_ALL);

Coloque isso no início do arquivo apenas para testes locais ou ambiente controlado.

Usando error_log para registrar detalhes

A função error_log permite gravar mensagens no log do servidor. Ela é útil para descobrir até onde o código está executando e quais valores estão chegando.

<?php

error_log('Iniciando processamento da API');

$id = $_GET['id'] ?? null;

error_log('ID recebido: ' . $id);

Você também pode registrar erros capturados em blocos try/catch.

<?php

try {
    // Código que pode gerar erro
} catch (Throwable $e) {
    error_log('Erro capturado: ' . $e->getMessage());
}

Erro 500 causado por erro de sintaxe

Um erro de sintaxe pode quebrar completamente o processamento do PHP. Exemplos comuns:

• Esquecer ponto e vírgula;
• Fechar chaves incorretamente;
• Usar aspas de forma errada;
• Chamar recurso incompatível com a versão do PHP;
• Colar código com caracteres invisíveis.

Exemplo com erro:

<?php

echo "Olá mundo"

O correto seria:

<?php

echo "Olá mundo";

O log geralmente mostra algo como Parse error ou syntax error.

Erro 500 causado por require ou include

Se sua aplicação tenta carregar um arquivo inexistente com require, o PHP pode gerar erro fatal.

<?php

require __DIR__ . '/config/database.php';

Se o caminho estiver errado, o log pode mostrar:

Failed opening required 'config/database.php'

Verifique:

• Se o arquivo existe;
• Se o nome está correto;
• Se há diferença entre maiúsculas e minúsculas;
• Se o caminho relativo está correto;
• Se o arquivo tem permissão de leitura.

Erro 500 causado por conexão com banco de dados

Falhas na conexão com MySQL também são causa comum de erro 500.

<?php

try {
    $pdo = new PDO(
        'mysql:host=localhost;dbname=sua_base;charset=utf8mb4',
        'usuario',
        'senha',
        [
            PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION
        ]
    );
} catch (PDOException $e) {
    error_log('Erro de conexão com banco: ' . $e->getMessage());

    http_response_code(500);
    echo json_encode([
        'success' => false,
        'message' => 'Erro interno no servidor.'
    ]);
    exit;
}

Em produção, registre a mensagem real no log, mas retorne uma mensagem genérica ao usuário.

Erro 500 causado por permissão de arquivos

Arquivos e pastas com permissões incorretas podem causar erro 500, principalmente em uploads, cache, logs ou sistemas que escrevem arquivos.

Exemplos de problemas:

• PHP sem permissão para gravar na pasta de upload;
• Arquivo PHP sem permissão de leitura;
• Pasta com dono incorreto;
• Permissões muito abertas bloqueadas pela hospedagem;
• Arquivo .htaccess com regra inválida.

Permissões comuns em Linux:

Arquivos: 644
Pastas: 755

Em alguns casos, pastas que precisam de escrita podem exigir configuração específica conforme o usuário do servidor web.

Erro 500 causado pelo .htaccess

Em servidores Apache, o arquivo .htaccess pode causar erro 500 se tiver uma regra inválida.

Exemplo de regra comum:

RewriteEngine On

RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php [QSA,L]

Problemas comuns no .htaccess:

• mod_rewrite desativado;
• Diretiva não permitida pela hospedagem;
• Erro de sintaxe na regra;
• Loop de redirecionamento;
• Uso de configuração incompatível com o servidor.

Para testar, renomeie temporariamente o arquivo .htaccess e veja se o erro desaparece.

Erro 500 em API PHP retornando HTML em vez de JSON

Em APIs, é comum o frontend esperar JSON. Se o PHP falhar antes de montar a resposta, o servidor pode retornar HTML ou resposta vazia.

Para evitar isso, padronize respostas de erro com JSON.

<?php

function jsonResponse(int $statusCode, array $data): void
{
    http_response_code($statusCode);
    header('Content-Type: application/json; charset=utf-8');

    echo json_encode($data, JSON_UNESCAPED_UNICODE);
    exit;
}

Depois, use essa função nos blocos de erro.

<?php

jsonResponse(500, [
    'success' => false,
    'message' => 'Erro interno no servidor.'
]);

Tratando exceptions com try/catch

O uso de try/catch ajuda a capturar falhas e impedir que a aplicação quebre sem controle.

<?php

try {
    $stmt = $pdo->prepare("SELECT * FROM usuarios WHERE id = :id");
    $stmt->execute([
        ':id' => $id
    ]);

    $usuario = $stmt->fetch();

    jsonResponse(200, [
        'success' => true,
        'data' => $usuario
    ]);

} catch (PDOException $e) {
    error_log('Erro PDO: ' . $e->getMessage());

    jsonResponse(500, [
        'success' => false,
        'message' => 'Erro interno ao consultar os dados.'
    ]);

} catch (Throwable $e) {
    error_log('Erro inesperado: ' . $e->getMessage());

    jsonResponse(500, [
        'success' => false,
        'message' => 'Erro interno no servidor.'
    ]);
}

Capturando exceptions não tratadas

Você pode configurar um handler global para exceptions não capturadas.

<?php

set_exception_handler(function (Throwable $e) {
    error_log('Exception não tratada: ' . $e->getMessage());

    http_response_code(500);
    header('Content-Type: application/json; charset=utf-8');

    echo json_encode([
        'success' => false,
        'message' => 'Erro interno no servidor.'
    ], JSON_UNESCAPED_UNICODE);

    exit;
});

Esse handler ajuda a evitar que exceptions escapem sem resposta controlada.

Capturando erros PHP com set_error_handler

Também é possível registrar erros PHP com set_error_handler.

<?php

set_error_handler(function ($severity, $message, $file, $line) {
    error_log("Erro PHP: {$message} em {$file}:{$line}");

    http_response_code(500);
    header('Content-Type: application/json; charset=utf-8');

    echo json_encode([
        'success' => false,
        'message' => 'Erro interno no servidor.'
    ], JSON_UNESCAPED_UNICODE);

    exit;
});

Esse tratamento ajuda a padronizar erros, mas ainda assim o log do servidor continua sendo fundamental.

Erro 500 por limite de memória

Quando o PHP ultrapassa o limite de memória, pode ocorrer erro fatal. O log geralmente mostra algo como:

Allowed memory size exhausted

Isso pode acontecer em:

• Consultas retornando muitos registros;
• Uploads grandes;
• Manipulação de imagens;
• Loops sem controle;
• Geração de relatórios grandes;
• Exportação de Excel ou PDF.

Melhor do que apenas aumentar memória é corrigir a causa, usando paginação, filtros, processamento em partes e consultas mais eficientes.

Erro 500 por tempo máximo de execução

Se uma requisição demora demais, o PHP pode encerrar o processamento. O log pode mostrar:

Maximum execution time exceeded

Causas comuns:

• Consulta SQL lenta;
• Loop pesado;
• API externa demorando para responder;
• Processamento de muitos arquivos;
• Geração de relatório muito grande.

Para resolver, revise a lógica, use paginação, crie índices no banco e evite tarefas muito pesadas em uma única requisição.

Erro 500 depois de atualizar o PHP

Após atualizar a versão do PHP, alguns códigos antigos podem parar de funcionar.

Verifique:

• Funções removidas ou depreciadas;
• Extensões não habilitadas;
• Versão do Composer incompatível;
• Pacotes antigos;
• Diferenças de configuração entre versões;
• Erros de tipagem mais rigorosos.

Nesse cenário, os logs normalmente mostram qual função, classe ou extensão está causando a falha.

Como criar um log personalizado da aplicação

Além do log do servidor, você pode criar um arquivo próprio para registrar eventos importantes da aplicação.

<?php

function appLog(string $message): void
{
    $arquivo = __DIR__ . '/logs/app.log';

    if (!is_dir(dirname($arquivo))) {
        mkdir(dirname($arquivo), 0755, true);
    }

    $linha = '[' . date('Y-m-d H:i:s') . '] ' . $message . PHP_EOL;

    file_put_contents($arquivo, $linha, FILE_APPEND);
}

appLog('Iniciando endpoint de usuários');

Esse tipo de log ajuda no diagnóstico de APIs, webhooks, rotas protegidas e integrações externas.

Exemplo completo de API PHP com tratamento para erro 500

<?php

header('Content-Type: application/json; charset=utf-8');

ini_set('display_errors', 0);
ini_set('log_errors', 1);
error_reporting(E_ALL);

function jsonResponse(int $statusCode, array $data): void
{
    http_response_code($statusCode);
    echo json_encode($data, JSON_UNESCAPED_UNICODE);
    exit;
}

set_exception_handler(function (Throwable $e) {
    error_log('Exception não tratada: ' . $e->getMessage());

    jsonResponse(500, [
        'success' => false,
        'message' => 'Erro interno no servidor.'
    ]);
});

try {
    $pdo = new PDO(
        'mysql:host=localhost;dbname=sua_base;charset=utf8mb4',
        'usuario',
        'senha',
        [
            PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
            PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC
        ]
    );

    $id = isset($_GET['id']) ? (int) $_GET['id'] : 0;

    if ($id <= 0) {
        jsonResponse(422, [
            'success' => false,
            'message' => 'ID inválido.'
        ]);
    }

    $stmt = $pdo->prepare("SELECT id, nome, email FROM usuarios WHERE id = :id");
    $stmt->bindValue(':id', $id, PDO::PARAM_INT);
    $stmt->execute();

    $usuario = $stmt->fetch();

    if (!$usuario) {
        jsonResponse(404, [
            'success' => false,
            'message' => 'Usuário não encontrado.'
        ]);
    }

    jsonResponse(200, [
        'success' => true,
        'data' => $usuario
    ]);

} catch (PDOException $e) {
    error_log('Erro PDO: ' . $e->getMessage());

    jsonResponse(500, [
        'success' => false,
        'message' => 'Erro interno ao consultar o banco de dados.'
    ]);

} catch (Throwable $e) {
    error_log('Erro geral: ' . $e->getMessage());

    jsonResponse(500, [
        'success' => false,
        'message' => 'Erro interno no servidor.'
    ]);
}

Checklist para corrigir erro 500 em PHP

• Verifique o log do Apache, Nginx ou PHP-FPM;
• Confirme se o arquivo PHP não tem erro de sintaxe;
• Teste se os caminhos de require e include estão corretos;
• Confira permissões de arquivos e pastas;
• Revise regras do .htaccess;
• Verifique conexão com banco de dados;
• Veja se alguma extensão PHP está faltando;
• Confirme limites de memória e tempo de execução;
• Registre erros com error_log;
• Use try/catch em operações críticas;
• Não exponha mensagens internas em produção;
• Padronize respostas JSON em APIs.

Erros comuns ao tentar corrigir erro 500

1. Tentar corrigir sem olhar o log

O log mostra a causa real. Sem ele, você fica apenas testando hipóteses.

2. Ativar display_errors em produção

Exibir erros diretamente para o usuário pode revelar informações sensíveis.

3. Ignorar o .htaccess

Uma única regra inválida pode derrubar todo o site em servidores Apache.

4. Não tratar erro de banco

Falhas de conexão ou consultas incorretas devem ser capturadas com try/catch.

5. Não diferenciar ambiente de produção e desenvolvimento

Em desenvolvimento, você pode exibir detalhes. Em produção, o correto é registrar em log e retornar mensagem genérica.

Conclusão

O erro 500 em PHP indica uma falha interna no servidor, mas a causa real quase sempre está registrada em algum log. Por isso, o melhor caminho é verificar os logs do Apache, Nginx, PHP-FPM ou PHP antes de alterar o código no escuro.

Depois de identificar a mensagem real, fica muito mais fácil corrigir o problema, seja ele um erro de sintaxe, conexão com banco, permissão de arquivo, configuração incorreta, limite de memória ou exception não tratada.

Em APIs PHP, também é importante padronizar respostas JSON, registrar detalhes com error_log e evitar expor mensagens internas para o usuário final. Assim, sua aplicação fica mais segura, profissional e fácil de manter.

Perguntas frequentes sobre erro 500 em PHP

O que é erro 500 em PHP?

É um erro interno do servidor que indica que o PHP ou a configuração do servidor falhou ao processar a requisição.

Como descobrir a causa do erro 500?

O melhor caminho é verificar os logs do Apache, Nginx, PHP-FPM ou PHP. O log geralmente mostra a mensagem real do erro.

Erro 500 pode ser causado por .htaccess?

Sim. Em servidores Apache, regras incorretas no .htaccess podem causar erro 500.

Posso ativar display_errors para corrigir?

Em ambiente de desenvolvimento, sim. Em produção, o ideal é manter os erros ocultos e registrar detalhes em log.

Erro de banco pode causar erro 500?

Sim. Falhas na conexão com MySQL, consultas inválidas ou exceptions não tratadas podem gerar erro 500.

Como evitar tela branca em PHP?

Ative logs, trate exceptions com try/catch, configure handlers globais e padronize respostas de erro.

Perguntas frequentes sobre erro 500 em PHP

O que é erro 500 em PHP?

É um erro interno do servidor que indica que o PHP ou a configuração do servidor falhou ao processar a requisição.

Como descobrir a causa do erro 500?

O melhor caminho é verificar os logs do Apache, Nginx, PHP-FPM ou PHP. O log geralmente mostra a mensagem real do erro.

Erro 500 pode ser causado por .htaccess?

Sim. Em servidores Apache, regras incorretas no .htaccess podem causar erro 500.

Posso ativar display_errors para corrigir?

Em ambiente de desenvolvimento, sim. Em produção, o ideal é manter os erros ocultos e registrar detalhes em log.

Erro de banco pode causar erro 500?

Sim. Falhas na conexão com MySQL, consultas inválidas ou exceptions não tratadas podem gerar erro 500.

Como evitar tela branca em PHP?

Ative logs, trate exceptions com try/catch, configure handlers globais e padronize respostas de erro.