PHP Lendo Erros

Todo mundo que programa vê mensagens de erro, todos os dias, inclusive quem programa há vinte anos. A diferença é que quem tem experiência lê a mensagem e quem está começando costuma se assustar e fechar a janela. Nesta aula você vai aprender a ler o que o PHP diz quando algo dá errado: que tipo de problema é, o que aconteceu e em que linha. Quase sempre a resposta está escrita ali.

Todas as mensagens desta página foram produzidas pelo PHP 8.5 de verdade, no computador da Ana (usuária ana, pasta /home/ana/erros). Elas vêm em inglês, sempre: o PHP não traduz as mensagens. Por isso cada uma ganha tradução aqui.

A ideia: o erro é um bilhete, não uma bronca

Pense na professora que devolve a prova com um bilhete na margem: "Questão 3, linha 2: faltou o sinal de menos". O bilhete diz quão grave é (errou a questão inteira ou só perdeu meio ponto?), o que está errado e onde. Você não precisa adivinhar nada: é só ir até lá e consertar.

A mensagem do PHP é esse bilhete. Veja um programa com um pequeno engano: a variável foi criada como $nome (com n minúsculo), mas foi usada como $Nome (com N maiúsculo). Para o PHP, são duas variáveis diferentes (veja Variáveis).

<?php
$nome = "Ana";
echo "Olá, $Nome!\n";

$ php ola.php

Warning: Undefined variable $Nome in /home/ana/erros/ola.php on line 3
Olá, !

Anatomia da mensagem

Warning:

A gravidade. Warning = "aviso": algo estranho aconteceu, mas o programa continuou. Por isso o Olá, ! apareceu depois.

Undefined variable $Nome

O que aconteceu: "variável não definida: $Nome". Você usou uma variável que nunca recebeu valor.

in /home/ana/erros/ola.php

Em qual arquivo (in = "em"). Num projeto com muitos arquivos, isso importa.

on line 3

Em qual linha (on line = "na linha"). Conte as linhas do arquivo: a 1 é o <?php, a 3 é o echo.

Repare também na linha em branco antes do Warning:: o PHP sempre pula uma linha antes da mensagem, para ela não grudar no que já estava na tela. E repare no resultado: como $Nome não existe, ela valeu "nada", e a frase saiu Olá, !.

Todas as mensagens do PHP seguem esse formato: gravidade: o que aconteceu in arquivo on line N. Quando você souber ler essas quatro partes, já saberá ler 90% dos erros.

Os tipos de mensagem: do mais grave ao mais leve

A primeira palavra da mensagem diz quão sério é o problema e, principalmente, se o programa parou.

Vamos ver cada um com um exemplo real.

Parse error: o PHP não conseguiu ler o seu código

Antes de executar qualquer coisa, o PHP lê o arquivo inteiro e confere se ele está escrito de acordo com as regras da linguagem (a sintaxe). Esse trabalho se chama parse ("análise"). Se algo não se encaixa, ele desiste e mostra um Parse error. Nenhuma linha roda, nem as que estavam certas:

<?php
echo "Linha 1\n";
echo "Linha 2\n";
echo "Linha 3\n"
echo "Linha 4\n";

$ php linhas.php

Parse error: syntax error, unexpected token "echo", expecting "," or ";" in /home/ana/erros/linhas.php on line 5

Nem a Linha 1 apareceu. A mensagem, traduzida:

Parse error: syntax error

"Erro de análise: erro de sintaxe." O código está mal escrito.

unexpected token "echo"

"Encontrei um echo que eu não esperava." Unexpected = inesperado; token = "pedaço" do código (uma palavra, um sinal).

expecting "," or ";"

"Eu esperava uma vírgula ou um ponto e vírgula." Essa é a dica de ouro: diz exatamente o que faltou.

on line 5

O PHP percebeu o problema na linha 5, quando chegou ao echo. Mas quem esqueceu o ; foi a linha 4.

O PHP não sabe onde você queria colocar o ;. Ele só sabe onde percebeu que algo estava errado: no primeiro pedaço que não fazia sentido. Por isso, num Parse error, olhe a linha indicada e a de cima. Nas próximas seções você vai ver os "pedaços inesperados" mais comuns.

Fatal error: o programa parou no meio

Aqui o código está bem escrito, então o PHP começa a rodar. Tudo vai bem até uma linha que pede algo impossível. Nesse ponto ele para, e o resto não roda:

<?php
echo "Antes\n";
echo $x;
echo "Depois\n";
echo naoExiste();
echo "Nunca aparece\n";

$ php parou.php
Antes

Warning: Undefined variable $x in /home/ana/erros/parou.php on line 3
Depois

Fatal error: Uncaught Error: Call to undefined function naoExiste() in /home/ana/erros/parou.php:5
Stack trace:
#0 {main}
  thrown in /home/ana/erros/parou.php on line 5
$ echo $?
255

Leia a saída de cima para baixo e você vê a história do programa: Antes saiu; a linha 3 deu um aviso e o programa continuou (Depois saiu); a linha 5 deu um erro fatal e o programa parou (Nunca aparece nunca apareceu). O echo $? mostra o código de saída: 255 é o jeito de o PHP avisar ao terminal "terminei com erro fatal"; um programa que termina bem sai com 0.

A mensagem do erro fatal é maior. Parte por parte:

Fatal error:

Erro fatal: o programa parou.

Uncaught Error:

"Erro não capturado." No PHP 8, a maioria dos erros fatais é um objeto de erro que o PHP "lança" (throw). Se ninguém o "captura" (catch), o programa para. Você vai aprender a capturar em Exceções (try e catch); por enquanto, leia Uncaught como "e ninguém tratou".

Call to undefined function naoExiste()

O que aconteceu: "chamada a uma função não definida: naoExiste()".

in /home/ana/erros/parou.php:5

Arquivo e linha, num formato curto: arquivo:linha.

Stack trace:

"Rastro da pilha": o caminho de funções que levou até o erro, do mais recente (#0) ao mais antigo. Aqui o erro aconteceu direto no programa principal ({main}), então o rastro é curto. Ele fica útil quando você tiver funções chamando funções.

thrown in … on line 5

"Lançado em … na linha 5": repete o lugar, no formato de sempre.

Warning: um aviso, e o programa segue

O aviso é o tipo mais traiçoeiro, justamente porque o programa não para. Ele continua com um valor errado (no exemplo da Ana, a variável inexistente virou "nada") e o resultado sai estranho: Olá, !. Nunca ignore um Warning: ele quase sempre é um engano seu que vai virar um bug.

Deprecated: funciona, mas está com os dias contados

Deprecated quer dizer "desaprovado, obsoleto". É o PHP avisando: "isso ainda funciona, mas uma versão futura vai remover; troque". Acontece muito com códigos antigos copiados da internet. Um exemplo novo do PHP 8.5: os nomes compridos de conversão de tipo, como (integer), viraram obsoletos.

<?php
$idade = (integer) "29";
echo $idade, "\n";

$ php idade.php

Deprecated: Non-canonical cast (integer) is deprecated, use the (int) cast instead in /home/ana/erros/idade.php on line 2
29

Tradução: "A conversão não padrão (integer) está obsoleta; use a conversão (int) no lugar." O programa funcionou (29 saiu), e a própria mensagem diz como consertar: trocar (integer) por (int). Mensagens Deprecated costumam ser assim, educadas e com a solução. Conversões de tipo são assunto de Conversão de Tipos.

Notice: uma observação

Antigamente o PHP tinha muitos notices; no PHP 8, quase todos viraram Warning. Os que sobraram são raros, por exemplo:

$ php final.php

Notice: Only variables should be passed by reference in /home/ana/erros/final.php on line 2
c

Você não precisa entender este agora ("só variáveis deveriam ser passadas por referência"). Guarde só que Notice é o mais leve de todos e que o programa continua. A lista completa de tipos fica em Tipos de Erro.

<?php
echo "Antes\n";
echo $x, "\n";
echo "Depois\n";
echo strtoupperr("fim"), "\n";

<?php
echo "Antes\n";
$x = 10;
echo $x, "\n";
echo "Depois\n";
echo strtoupper("fim"), "\n";

A linha nem sempre é a do erro

O PHP indica a linha onde percebeu o problema, que nem sempre é a linha onde ele está. Isso acontece quase só com Parse error. Veja este arquivo, com duas linhas em branco depois do echo sem ponto e vírgula:

<?php
echo "Olá"


$x = 1;

$ php longe.php

Parse error: syntax error, unexpected variable "$x", expecting "," or ";" in /home/ana/erros/longe.php on line 5

O ; faltou na linha 2, mas o PHP aponta a 5. Para ele, linhas em branco não contam: depois de echo "Olá" veio direto $x, e só ali ele percebeu que faltava algo. A regra prática:

1. Vá até a linha indicada.
2. Se ela parece certa, suba: olhe a última linha com código antes dela.
3. Se a mensagem fala em end of file (fim do arquivo), procure algo aberto e não fechado: aspas, (, {. Aí o problema pode estar bem longe, lá em cima.

Conferir a escrita sem rodar: php -l

A opção -l (de lint, "fiapo": catar pequenos defeitos) faz o PHP só ler o arquivo e dizer se a sintaxe está certa, sem executar nada. Ela encontra os Parse error, não os outros (para achar um Warning, o programa precisa rodar).

$ php -l linhas.php

Parse error: syntax error, unexpected token "echo", expecting "," or ";" in linhas.php on line 5
Errors parsing linhas.php
$ echo $?
255
$ php -l ola.php
No syntax errors detected in ola.php

No syntax errors detected = "nenhum erro de sintaxe encontrado". Errors parsing = "erros ao analisar". É útil antes de enviar um arquivo para o servidor: um Parse error no ar derruba a página inteira.

Onde a mensagem aparece: terminal × navegador

Até aqui você rodou tudo no terminal (o modo CLI, de command line interface). Quando o mesmo PHP gera uma página web, a mensagem aparece de outro jeito. E, num site de verdade, muitas vezes ela nem aparece. Quem decide isso são duas configurações: display_errors e error_reporting.

display_errors: mostrar ou esconder

display_errors ("exibir os erros") decide se as mensagens vão para a saída do programa: a tela do terminal ou a página que o navegador recebe. Ligado (1 ou On), você vê as mensagens. Desligado (0 ou Off), elas somem, mas o erro continua acontecendo. Você pode mudar só para uma execução com -d ("definir"):

$ php ola.php

Warning: Undefined variable $Nome in /home/ana/erros/ola.php on line 3
Olá, !
$ php -d display_errors=0 ola.php
Olá, !                               « o aviso sumiu, mas o problema continua

Com um erro fatal e display_errors desligado, o resultado é o pior de todos: nada. Nenhuma saída, nenhuma explicação. Só o código de saída denuncia:

$ php -d display_errors=0 parou.php
Antes
Depois
$ echo $?
255                                  « parou com erro fatal, em silêncio

No navegador: as mesmas mensagens, em HTML

Esta página tem os mesmos dois enganos (a variável $Nome e uma função que não existe):

<?php
$nome = "Ana";
echo "<p>Olá, $Nome!</p>\n";
echo "<p>Total: " . contar() . "</p>\n";

Abrindo pelo servidor embutido (php -S localhost:8000), o navegador recebe este HTML:

$ curl -s localhost:8000/pagina.php
<br />
<b>Warning</b>:  Undefined variable $Nome in <b>/home/ana/erros/pagina.php</b> on line <b>3</b><br />
<p>Olá, !</p>
<br />
<b>Fatal error</b>:  Uncaught Error: Call to undefined function contar() in /home/ana/erros/pagina.php:4
Stack trace:
#0 {main}
  thrown in <b>/home/ana/erros/pagina.php</b> on line <b>4</b><br />

A mensagem é a mesma, só que com etiquetas HTML: <b> (negrito) na gravidade, no arquivo e na linha, e <br /> (quebra de linha) no lugar das linhas em branco. No navegador, você vê o texto em negrito, misturado com a sua página. Isso é a configuração html_errors, que vem ligada no modo web e desligada no terminal.

Agora o mesmo servidor, com display_errors desligado (php -d display_errors=0 -S localhost:8000), numa página em que o erro fatal acontece antes de qualquer saída:

<?php
$total = contar();
echo "<p>Total: $total</p>";

$ curl -si localhost:8000/pagina2.php
HTTP/1.0 500 Internal Server Error
Host: localhost:8000
Date: Fri, 16 Oct 2026 23:44:39 GMT
Connection: close
X-Powered-By: PHP/8.5.8
Content-type: text/html; charset=UTF-8
                                     « e mais nada: a página veio vazia

Esta é a famosa "tela branca": o navegador recebe o código 500 Internal Server Error ("erro interno do servidor") e uma página vazia (ou a página padrão de erro do navegador). Nenhuma pista. A pista está no registro (log) do servidor. No servidor embutido, o registro é o próprio terminal onde ele está rodando:

[Fri Oct 16 20:44:32 2026] 127.0.0.1:54500 [200]: GET /pagina.php - Uncaught Error: Call to undefined function contar() in /home/ana/erros/pagina.php:4
Stack trace:
#0 {main}
  thrown in /home/ana/erros/pagina.php on line 4

Ligado no seu computador, desligado no site no ar

Essas configurações moram no arquivo php.ini. O comando php --ini mostra qual arquivo está sendo usado, e php -i mostra os valores atuais. No computador da Ana, o PHP não tem php.ini, então vale o padrão de fábrica do terminal: mostrar tudo.

$ php -i | grep -E "^(display_errors|error_reporting|log_errors|html_errors)"
display_errors => STDOUT => STDOUT
error_reporting => no value => no value
html_errors => Off => Off
log_errors => Off => Off

STDOUT quer dizer "ligado, na saída normal". error_reporting sem valor quer dizer "o padrão", que no PHP 8 é todos os tipos. No Debian e no Ubuntu, o PHP instalado pelo apt tem um php.ini para o terminal e outro para o servidor web, em /etc/php/8.x/ (veja Instalar no Linux); a versão do servidor web costuma vir com display_errors desligado.

$ php -d log_errors=1 ola.php
PHP Warning:  Undefined variable $Nome in /home/ana/erros/ola.php on line 3

Warning: Undefined variable $Nome in /home/ana/erros/ola.php on line 3
Olá, !

error_reporting: quais tipos contam

error_reporting ("relatar erros") escolhe quais tipos de mensagem o PHP leva em conta. Cada tipo tem uma constante com o nome dele:

Você pode mudar as duas configurações dentro do programa, nas primeiras linhas. É comum ver isto no topo de arquivos de quem está desenvolvendo:

<?php
error_reporting(E_ALL);
ini_set('display_errors', '1');

echo "Olá, $Nome!\n";

error_reporting(E_ALL);

"Leve em conta todos os tipos de mensagem."

ini_set('display_errors', '1');

Muda uma configuração do php.ini só para este programa (ini_set = "definir no ini"): "mostre as mensagens".

$ php -d display_errors=0 config.php

Warning: Undefined variable $Nome in /home/ana/erros/config.php on line 5
Olá, !                               « o ini_set venceu o -d

$ php -d display_errors=0 config2.php
$ echo $?
255

E não esconda avisos para "consertar" o programa. Desligar os Warning com error_reporting(E_ALL & ~E_WARNING) só tira o bilhete da sua frente; o engano continua lá e o resultado continua errado (Olá, !). Erros são tratados de verdade em Exceções e Depurar.

Os 10 erros mais comuns de quem começa

Cada caso abaixo foi rodado no PHP 8.5. Guarde esta seção: quando aparecer um erro que você não entende, procure aqui pela mensagem. Para a lista completa, veja Mensagens de Erro.

<?php
$nome = "Ana"
echo "Olá, $nome!\n";

$ php e1.php

Parse error: syntax error, unexpected token "echo" in /home/ana/erros/e1.php on line 3

<?php
echo "Olá, mundo!\n;
echo "Tchau!\n";

$ php e2.php

Parse error: syntax error, unexpected identifier "Tchau", expecting "," or ";" in /home/ana/erros/e2.php on line 3

<?php
$nota = 8;
if ($nota >= 7) {
    echo "Aprovada!\n";

echo "Fim\n";

$ php e3.php

Parse error: Unclosed '{' on line 3 in /home/ana/erros/e3.php on line 7

<?php
$nota = 8;
if ($nota >= 7 {
    echo "Aprovada!\n";
}

$ php f1.php

Parse error: syntax error, unexpected token "{" in /home/ana/erros/f1.php on line 3

<?php
$nome = "Ana";
echo "Olá, $Nome!\n";

$ php e4.php

Warning: Undefined variable $Nome in /home/ana/erros/e4.php on line 3
Olá, !

<?php
$nome = "Ana";
echo nome;

$ php e6.php

Fatal error: Uncaught Error: Undefined constant "nome" in /home/ana/erros/e6.php:3
Stack trace:
#0 {main}
  thrown in /home/ana/erros/e6.php on line 3

<?php
$texto = "banana";
echo strlenn($texto);

$ php e7.php

Fatal error: Uncaught Error: Call to undefined function strlenn() in /home/ana/erros/e7.php:3
Stack trace:
#0 {main}
  thrown in /home/ana/erros/e7.php on line 3

<?php
$aluna = ["nome" => "Ana", "nota" => 9];
echo $aluna["idade"];
echo "\n";
$frutas = ["maçã", "pera"];
echo $frutas[2];

$ php e8.php

Warning: Undefined array key "idade" in /home/ana/erros/e8.php on line 3


Warning: Undefined array key 2 in /home/ana/erros/e8.php on line 6

<?php
$nome = "Ana";
echo "Olá, " + $nome;

$ php e10.php

Fatal error: Uncaught TypeError: Unsupported operand types: string + string in /home/ana/erros/e10.php:3
Stack trace:
#0 {main}
  thrown in /home/ana/erros/e10.php on line 3

<?php
$total = 100;
$pessoas = 0;
echo $total / $pessoas;

$ php e9.php

Fatal error: Uncaught DivisionByZeroError: Division by zero in /home/ana/erros/e9.php:4
Stack trace:
#0 {main}
  thrown in /home/ana/erros/e9.php on line 4

echo "Olá, mundo!\n";

$ php f4.php
echo "Olá, mundo!\n";

<?php
$cidade = "Recife";
echo $cidade, "\n";

<?php
$cidade = "Recife";
echo cidade, "\n";

Roteiro para qualquer erro

Quando uma mensagem aparecer, siga sempre a mesma ordem:

1. Leia a primeira palavra. Parse error? O problema é de escrita (pontuação, aspas, chaves). Fatal error? O código está bem escrito, mas pediu algo impossível. Warning? O programa seguiu com um valor errado.
2. Leia o "o que aconteceu", traduzindo palavra por palavra. Undefined = não definido; unexpected = inesperado; expecting = esperava; unclosed = não fechado; call to = chamada a.
3. Vá até o arquivo e a linha. Num Parse error, olhe também a linha de cima.
4. Conserte só o primeiro erro e rode de novo. Um erro no começo pode causar outros mais para baixo; muitas vezes eles somem juntos.
5. Ainda não entendeu? Copie a parte fixa da mensagem (sem o seu caminho e o número da linha), como Undefined array key, e procure em Mensagens de Erro ou num buscador.

<?php
$produto = "Caderno";
$preco = 12.5;
$qtd = 3

$total = $preco * $qtd;
echo "Produto: " . $Produto . "\n";
echo "Total: R$ " + $total . "\n";

<?php
$produto = "Caderno";
$preco = 12.5;
$qtd = 3;

$total = $preco * $qtd;
echo "Produto: " . $produto . "\n";
echo "Total: R$ " . $total . "\n";

No PHP real, a sequência de mensagens foi esta. Primeiro, o Parse error (o ; que falta na linha 4 só é notado na linha 6, por causa da linha em branco):

$ php loja.php

Parse error: syntax error, unexpected variable "$total" in /home/ana/erros/loja.php on line 6

Depois de colocar o ;, o programa roda até a linha 8:

$ php loja.php

Warning: Undefined variable $Produto in /home/ana/erros/loja.php on line 7
Produto:

Fatal error: Uncaught TypeError: Unsupported operand types: string + float in /home/ana/erros/loja.php:8
Stack trace:
#0 {main}
  thrown in /home/ana/erros/loja.php on line 8

Com $produto minúsculo e o . no lugar do +:

$ php loja.php
Produto: Caderno
Total: R$ 37.5

Referência

Exercícios

Resumo

• Toda mensagem do PHP tem quatro partes: gravidade, o que aconteceu, arquivo (in) e linha (on line).
• Parse error: o código está mal escrito; nenhuma linha roda. Fatal error: o programa para naquela linha. Warning, Deprecated e Notice: o programa continua, possivelmente com valores errados.
• Num Parse error, o problema costuma estar na linha indicada ou antes; end of file = algo ficou aberto.
• php -l confere a sintaxe sem rodar. echo $? igual a 255 = terminou com erro.
• display_errors mostra ou esconde as mensagens; error_reporting escolhe os tipos. Ligados no seu computador, display_errors desligado no site no ar (os erros vão para o log).
• No navegador, a mensagem vem em HTML (<b>Warning</b>); com display_errors desligado, um erro fatal vira tela branca e 500.
• Conserte o primeiro erro e rode de novo. Nunca esconda avisos: conserte a causa.