Lendo mensagens de erro: a anatomia do traceback

A anatomia do traceback

Quando uma exceção derruba o programa, o interpretador imprime um relatório chamado traceback. O nome vem de rastrear de volta: ele refaz o caminho que o programa percorreu até o ponto do desastre. Para o iniciante, aquele bloco de texto parece punição; para quem sabe ler, é o Python entregando o culpado com endereço e foto. Veja um traceback real, gerado por um programa de duas linhas que tenta converter texto em número.

Traceback (most recent call last):
  File "conversao.py", line 2, in <module>
    idade = int(texto)
            ^^^^^^^^^^
ValueError: invalid literal for int() with base 10: 'vinte'

Um traceback completo. Cinco linhas, quatro informações: o aviso, o endereço, o código e o veredito.

1. Cabeçalho: Traceback (most recent call last) avisa que o relatório começou e que a chamada mais recente vem por último.
2. Localização: File "conversao.py", line 2 diz o arquivo e a linha; in <module> indica que o erro está no corpo principal, fora de qualquer função.
3. A linha do código: o Python copia a linha exata que estourou, para você nem precisar abrir o arquivo.
4. A seta: os acentos circunflexos (^) sublinham o trecho preciso da linha que causou o problema.
5. O veredito: a última linha traz o tipo do erro (ValueError) e a mensagem, que aqui até mostra o valor culpado: 'vinte'.

Traduzindo o veredito para português: valor inválido para int() na base 10. Ou seja, a função int() recebeu a palavra vinte e não conseguiu transformá-la em número. Repare que a mensagem entrega até o valor problemático entre aspas. O Python não esconde nada; ele só fala em inglês técnico.

A regra de ouro: de baixo para cima

O instinto de todo mundo é ler o traceback como se lê um texto: de cima para baixo. Resista. A informação mais valiosa mora na última linha, o tipo e a mensagem do erro, e é por ela que a leitura deve começar. Só depois de saber O QUE aconteceu vale a pena subir para descobrir ONDE: o campo line e a linha de código copiada. Em programas grandes, o traceback pode ter dezenas de linhas mostrando função chamando função; a última linha continua sendo o resumo, e a de cima dela, o endereço mais próximo do crime.

1. Leia a ÚLTIMA linha: qual é o tipo (ValueError? TypeError?) e o que a mensagem diz.
2. Suba uma linha por vez até achar o primeiro File que aponta para um arquivo SEU.
3. Anote o número da linha e olhe o trecho de código copiado, com a seta.
4. Vá até essa linha no seu editor e corrija com a informação do tipo em mãos.

Um detalhe prático que economiza tempo: a mensagem da última linha é a melhor coisa para pesquisar na internet quando você não entender o erro. Copie o tipo e a mensagem, sem os seus nomes de variáveis, e a busca devolve gente que passou pelo mesmo problema. Essa é uma das habilidades mais usadas da profissão, e ninguém conta para o iniciante.

Treino: três tracebacks reais, comentados

Teoria vista, hora do treino. Abaixo estão três tracebacks reais, gerados por programas curtos no Python 3.12. Para cada um, aplique o método: última linha primeiro, depois o endereço. Tente traduzir sozinho antes de ler a legenda.

Traceback (most recent call last):
  File "saudacao.py", line 2, in <module>
    print(nomme)
          ^^^^^
NameError: name 'nomme' is not defined. Did you mean: 'nome'?

Traceback 1. Veredito: NameError, o nome nomme não existe. O programa criou a variável nome e tentou usar nomme, com erro de digitação. O Python 3.12 até sugere a correção: Did you mean: 'nome'?

Traceback (most recent call last):
  File "soma.py", line 1, in <module>
    total = "10" + 5
            ~~~~~^~~
TypeError: can only concatenate str (not "int") to str

Traceback 2. Veredito: TypeError, só dá para concatenar texto com texto. A linha 1 tentou somar o texto "10" com o número 5; os tils e a seta marcam a operação inteira e o operador culpado.

Traceback (most recent call last):
  File "media.py", line 3, in <module>
    media = soma / quantidade
            ~~~~~^~~~~~~~~~~~
ZeroDivisionError: division by zero

Traceback 3. Veredito: ZeroDivisionError, divisão por zero. Na linha 3, a variável quantidade valia 0. O erro real quase nunca está na divisão em si, e sim em quem deixou o zero chegar até ela.