Mensagens de erro em Python: como ler e corrigir bugs comuns

Iniciante20 min6 exercícios75 XP

Este tutorial foi traduzido do original em inglês.Read in English Leer en español Читать на русском อ่านภาษาไทย Avisar sobre um erro de tradução

Antes de começar

Python para iniciantes: seu primeiro programa em 5 minutos

0/6 exercícios

Quando iniciantes veem uma mensagem de erro em vermelho, o primeiro instinto é entrar em pânico. A tela se enche de um texto assustador, e a pessoa acha que causou um estrago sério. Mas a verdade é esta: as mensagens de erro são suas melhores amigas. Elas dizem exatamente o que deu errado e onde.

Programadores profissionais encontram erros todos os dias. A diferença entre um iniciante e um especialista não é que o especialista evita erros: é que ele sabe lê-los. Depois que você aprende a ler as mensagens de erro do Python, a depuração deixa de ser assustadora e vira algo quase automático.

Neste tutorial, você vai aprender a ler um traceback do Python, entender os seis tipos de erro mais comuns e montar um kit mental de ferramentas para corrigir bugs rapidamente.

Como ler um traceback do Python

Quando o Python encontra um erro, ele exibe um traceback: um relatório que conta o que aconteceu. A maioria das pessoas lê tracebacks de cima para baixo. É justamente o contrário do que se deve fazer. Comece sempre pela última linha.

Código que gera um traceback

def greet(name):

message = 'Hello, ' + name

return message

result = greet(42)

Saída

Traceback (most recent call last):
  File "<exec>", line 5, in <module>
  File "<exec>", line 2, in greet
TypeError: can only concatenate str (not "int") to str

Quando você executa este código, o Python mostra um traceback. Veja como lê-lo, começando de baixo:

SyntaxError: o Python não entende seu código

Um SyntaxError significa que o Python nem consegue começar a executar seu código, porque a estrutura está errada. É como um erro de gramática em português: a frase não faz sentido. O Python detecta esses erros antes de executar uma única linha.

Causas comuns de SyntaxError

# Missing colon after if

try:

exec('if True\n print("hello")')

except SyntaxError as e:

print(f'SyntaxError: {e}')

# These are the most common causes:

print('Common SyntaxError causes:')

print('1. Missing colon after if/else/for/while/def')

print('2. Mismatched parentheses or quotes')

print('3. Using = instead of == in conditions')

print('4. Incorrect indentation')

Saída

SyntaxError: expected ':' (<string>, line 1)
Common SyntaxError causes:
1. Missing colon after if/else/for/while/def
2. Mismatched parentheses or quotes
3. Using = instead of == in conditions
4. Incorrect indentation

A boa notícia: os SyntaxErrors costumam ser os mais rápidos de corrigir. Muitas vezes o Python aponta direto para o problema com uma pequena seta (^) que mostra onde ele se confundiu.

Com erro: faltam os dois-pontos

if temperature > 30
    print('Hot!')

Corrigido: dois-pontos adicionados

if temperature > 30:
    print('Hot!')

NameError: o Python não encontra esse nome

Um NameError significa que você usou um nome de variável ou de função que o Python não reconhece. Em geral, isso indica um erro de digitação, uma variável que você esqueceu de definir ou que usou antes de atribuir um valor.

Exemplos comuns de NameError

# Typo in variable name

username = 'Alice'

try:

print(usernme) # Oops - misspelled!

except NameError as e:

print(f'NameError: {e}')

# Using a variable before defining it

try:

print(score)

score = 100

except NameError as e:

print(f'NameError: {e}')

Saída

NameError: name 'usernme' is not defined
NameError: name 'score' is not defined

Bug: nome de variável digitado errado

total_price = 49.99
print(total_prce)  # typo!

Corrigido: grafia certa

total_price = 49.99
print(total_price)

TypeError: tipo errado para a operação

Um TypeError significa que você tentou fazer algo com o tipo de dado errado. Por exemplo, somar uma string com um número ou chamar algo que não é uma função. O Python entende o que você pediu, mas os tipos não combinam.

Exemplos comuns de TypeError

# Can't add string and integer

try:

result = 'Age: ' + 25

except TypeError as e:

print(f'TypeError: {e}')

# Can't multiply string by string

try:

result = 'hello' * 'world'

except TypeError as e:

print(f'TypeError: {e}')

# Wrong number of arguments

def add(a, b):

return a + b

try:

add(1, 2, 3)

except TypeError as e:

print(f'TypeError: {e}')

Saída

TypeError: can only concatenate str (not "int") to str
TypeError: can't multiply sequence by non-int of type 'str'
TypeError: add() takes 2 positional arguments but 3 were given

Os TypeErrors aparecem muito quando você trabalha com a entrada do usuário (que é sempre uma string) ou quando uma função retorna None sem você esperar.

Bug: misturando string e int

age = 25
print('You are ' + age + ' years old')

Corrigido: use f-string ou str()

age = 25
print(f'You are {age} years old')

IndexError e KeyError: acessando o que não existe

Um IndexError acontece quando você tenta acessar uma posição da lista que não existe. Um KeyError acontece quando você tenta acessar uma chave do dicionário que não existe. Os dois significam que você está tentando pegar algo que não está lá.

Exemplos de IndexError e KeyError

# IndexError - list index out of range

fruits = ['apple', 'banana', 'cherry']

try:

print(fruits[5]) # Only indices 0, 1, 2 exist!

except IndexError as e:

print(f'IndexError: {e}')

print(f'List length: {len(fruits)}')

print(f'Valid indices: 0 to {len(fruits) - 1}')

# KeyError - dictionary key doesn't exist

user = {'name': 'Alice', 'age': 25}

try:

print(user['email']) # This key doesn't exist!

except KeyError as e:

print(f'KeyError: {e}')

Saída

IndexError: list index out of range
List length: 3
Valid indices: 0 to 2
KeyError: 'email'

Nos dicionários, você pode evitar o KeyError usando o método .get(), que retorna um valor padrão em vez de travar o programa.

Trava com KeyError

user = {'name': 'Alice'}
email = user['email']  # KeyError!

Seguro com .get()

user = {'name': 'Alice'}
email = user.get('email', 'Not provided')
print(email)  # Not provided

ValueError: tipo certo, valor errado

Um ValueError significa que o tipo está certo, mas o valor em si não faz sentido para a operação. O exemplo clássico: tentar converter uma string que não é numérica em um número inteiro.

Exemplos comuns de ValueError

# Can't convert "hello" to an integer

try:

number = int('hello')

except ValueError as e:

print(f'ValueError: {e}')

# Can't convert a decimal string with int()

try:

number = int('3.14')

except ValueError as e:

print(f'ValueError: {e}')

# This works - go through float first

number = int(float('3.14'))

print(f'Converted: {number}')

Saída

ValueError: invalid literal for int() with base 10: 'hello'
ValueError: invalid literal for int() with base 10: '3.14'
Converted: 3

Os ValueErrors aparecem com frequência ao processar a entrada do usuário. A pessoa pode digitar "vinte" em vez de "20", ou deixar um campo em branco. Valide sempre a entrada antes de convertê-la.

Tratando ValueError com try/except

# Safe conversion pattern

user_input = 'abc'

try:

age = int(user_input)

print(f'Your age is {age}')

except ValueError:

print(f'\"{user_input}\" is not a valid number')

Saída

"abc" is not a valid number

Dicas comuns de depuração

Aqui está um guia de consulta rápida para depurar código Python. Essas técnicas funcionam para qualquer tipo de erro.

Esta é uma referência rápida dos erros que você vai encontrar com mais frequência:

Erro	O que significa	Correção rápida
`SyntaxError`	A estrutura do código está errada	Confira dois-pontos, parênteses e aspas
`NameError`	Variável ou função não encontrada	Confira a grafia, defina antes de usar
`TypeError`	Tipo de dado errado	Converta os tipos ou confira os argumentos da função
`IndexError`	Índice da lista fora do intervalo	Confira o tamanho da lista, lembre que os índices começam em 0
`KeyError`	Chave do dicionário não encontrada	Use `.get()` ou confira se a chave existe
`ValueError`	Tipo certo, valor errado	Valide os dados antes de converter

Exercícios práticos

Hora de praticar suas habilidades de depuração! A maioria destes exercícios traz código com erro para você corrigir. Leia a mensagem de erro, encontre o bug e conserte.

Exercício 1: corrija o SyntaxError

Corrija o erro

Este código tem um SyntaxError. Encontre e corrija o erro para que ele exiba:

Python is fun!
Let's learn more.

message = 'Python is fun!'

print(message

print('Let\'s learn more.')

Exercício 2: corrija o NameError

Corrija o erro

Este código tem um NameError. Encontre o erro de digitação e corrija-o para que o código exiba:

Hello, Alice! You have 3 new messages.

user_name = 'Alice'

message_count = 3

print(f'Hello, {user_name}! You have {mesage_count} new messages.')

Exercício 3: corrija o TypeError

Corrija o erro

Este código tem um TypeError. Corrija-o para que ele exiba:

Your total is $37.5

price = 12.5

quantity = '3'

total = price * quantity

print(f'Your total is ${total}')

Exercício 4: corrija o IndexError

Corrija o erro

Este código tenta exibir a última cor, mas trava com um IndexError. Corrija-o para que ele exiba:

Last color: green

colors = ['red', 'blue', 'green']

last_index = len(colors)

print(f'Last color: {colors[last_index]}')

Exercício 5: corrija o ValueError

Corrija o erro

Este código trava ao tentar converter uma string de preço em um número inteiro. Corrija-o para que ele exiba:

Price in cents: 999

O preço é "9.99" dólares, e queremos convertê-lo em centavos (multiplicar por 100 e transformar o resultado em um número inteiro).

price_str = '9.99'

price_cents = int(price_str) * 100

print(f'Price in cents: {price_cents}')

Exercício 6: corrija todos os bugs

Corrija o erro

Este código dá erro em cada uma das suas três seções, mas uma única correção pode resolver duas delas. Corrija-o para que a saída seja:

Student: Alice
Grade: 85
Passed: True

# Bug 1: Something wrong with the variable name

student_name = 'Alice'

print(f'Student: {student_Name}')

# Bug 2: Something wrong with the type

grade = '85'

print(f'Grade: {grade + 0}')

# Bug 3: Something wrong with the comparison

passed = grade >= 60

print(f'Passed: {passed}')

Resumo: mensagens de erro em Python

Esta é sua referência rápida para os erros mais comuns do Python:

Erro	Significado	O que conferir primeiro
`SyntaxError`	Estrutura do código inválida	Dois-pontos, parênteses e aspas faltando
`NameError`	Variável desconhecida	Grafia, ordem das definições
`TypeError`	Tipo errado	Confira os tipos com `type()`
`IndexError`	Índice de lista inválido	Tamanho da lista, índices a partir de 0
`KeyError`	Chave de dicionário inválida	Use `.get()` com um valor padrão
`ValueError`	Valor errado	Valide antes de converter

As regras de ouro da depuração:

Leia sempre primeiro a última linha do traceback

Confira o número da linha que o Python indica (e a linha anterior)

Use print(type(x), x) para inspecionar variáveis suspeitas

Mensagens de erro são ajudantes, não inimigas: elas dizem exatamente o que deu errado

O que vem a seguir?

Agora que você sabe ler mensagens de erro, está pronto para encarar com confiança assuntos mais complexos do Python. Siga para Listas em Python e conheça uma das estruturas de dados mais poderosas e versáteis do Python.

Como ler um traceback do Python

SyntaxError: o Python não entende seu código

NameError: o Python não encontra esse nome

TypeError: tipo errado para a operação

IndexError e KeyError: acessando o que não existe

ValueError: tipo certo, valor errado

Dicas comuns de depuração

Exercícios práticos

Resumo: mensagens de erro em Python

O que vem a seguir?

Tutoriais relacionados