Como Corrigir Erros em Python: 10 Erros Comuns

Se você está aprendendo Python, provavelmente já encontrou uma situação frustrante: executou seu código, esperou ver o resultado e, em vez disso, apareceu uma mensagem de erro cheia de palavras em inglês, nomes estranhos e números de linhas.

No início, isso pode parecer complicado. Você olha para a mensagem, tenta entender o que aconteceu e, às vezes, acaba modificando várias partes do código sem saber exatamente onde está o problema.

Essa dificuldade é comum entre iniciantes. Aprender a programar não significa apenas escrever comandos corretamente, mas também desenvolver a capacidade de identificar problemas, interpretar mensagens e encontrar soluções.

Neste guia, você vai aprender como corrigir erros em Python, conhecer dez erros frequentes e entender o que fazer quando eles aparecem. Para cada situação, veremos um exemplo incorreto, a mensagem esperada, a causa do problema e uma versão corrigida do código.

Também vamos explorar como interpretar um traceback e acompanhar um estudo de caso ilustrativo para mostrar como investigar um erro passo a passo.

Por que aparecem erros em Python?

Um programa é formado por instruções que precisam seguir determinadas regras. Quando uma dessas regras é desrespeitada ou quando o programa encontra uma situação que não consegue processar, pode ocorrer um erro.

Isso acontece por diferentes motivos:

• Uma palavra foi escrita incorretamente.

• Uma variável foi utilizada antes de ser definida.

• Uma operação foi realizada com tipos de dados incompatíveis.

• Um índice ou uma chave não existe.

• Um arquivo ou módulo não foi encontrado.

• Uma operação matematicamente inválida foi executada.

Em Python, é importante distinguir dois grupos de problemas: erros de sintaxe e exceções.

Os erros de sintaxe acontecem quando o interpretador não consegue analisar corretamente o código. Já as exceções normalmente surgem durante a execução, quando uma operação encontra uma situação problemática.

Compreender essa diferença ajuda a escolher a maneira correta de investigar cada situação.

Como interpretar uma mensagem de erro em Python?

Antes de conhecer os dez erros, vale aprender a ler as informações que o Python apresenta quando algo dá errado.

Imagine o seguinte programa:

nome = "Tiago"
idade = "25"

resultado = nome +  idade + 5

print(resultado)

Ao executar o código, você encontrará um TypeError, pois a expressão tenta somar uma string com um número inteiro.

A mensagem será semelhante a esta:

TypeError: can only concatenate str (not "int") to str

Essa mensagem parece complicada à primeira vista, mas contém informações úteis.

O que é um traceback?

Quando uma exceção não é tratada, o Python normalmente apresenta um traceback, que mostra o caminho da execução até o ponto em que o problema aconteceu.

Um traceback costuma conter:

• O nome do arquivo em execução.

• O número da linha relacionada ao problema.

• O trecho de código que estava sendo executado, quando disponível.

• O tipo da exceção.

• Uma descrição do que aconteceu.

A última linha geralmente é um bom ponto de partida, pois apresenta o nome da exceção e uma explicação resumida.

Como descobrir em qual linha está o erro?

Procure uma indicação semelhante a:

File "programa.py", line 4

Isso informa que o Python está apontando para a linha 4 do arquivo programa.py.

Entretanto, a linha indicada nem sempre contém exatamente o ponto que precisa ser corrigido. Um erro de sintaxe, por exemplo, pode ser detectado em um local diferente daquele em que o símbolo ausente deveria estar.

Leia a mensagem inteira, examine a linha indicada e confira também as instruções anteriores.

O que fazer quando não entende a mensagem?

Siga este procedimento:

1. Identifique o nome do erro, como TypeError ou NameError.

2. Leia a descrição que aparece depois desse nome.

3. Localize a linha indicada no traceback.

4. Verifique os valores, variáveis e operações envolvidos.

5. Faça uma alteração pequena e execute novamente o programa.

Evite modificar várias partes do código de uma só vez. Quando você altera uma coisa por vez, fica mais fácil perceber qual mudança resolveu o problema.

Para uma explicação mais detalhada sobre a linguagem, consulte o artigo O que é Python?.

Os 10 erros mais comuns em Python e como resolver

Os exemplos a seguir utilizam recursos disponíveis no Python 3.12 ou superior e podem ser adaptados a diferentes editores e ambientes de execução.

1. SyntaxError: erro de sintaxe

O SyntaxError acontece quando o código não segue a sintaxe esperada pelo Python.

Isso pode ocorrer por causa de parênteses ausentes, aspas não fechadas, dois-pontos esquecidos ou palavras-chave utilizadas incorretamente.

Exemplo incorreto:

idade = 25

if idade >= 18
    print("Maior de idade")

Nesse caso, faltam os dois-pontos (:) no final da condição.

A mensagem será semelhante a:

SyntaxError: expected ':'

Como corrigir:

idade = 25

if idade >= 18:
    print("Maior de idade")

Agora o código está sintaticamente correto e imprime Maior de idade.

Como evitar esse erro: confira os dois-pontos depois de if, elif, else, for, while, def e outras estruturas que exigem esse símbolo. Verifique também se os parênteses, colchetes e aspas foram fechados corretamente.

Se quiser revisar expressões e operadores utilizados nessas condições, consulte Expressões em Python.

2. IndentationError: erro de indentação

Python utiliza a indentação, ou seja, os espaços no início das linhas, para definir blocos de código.

Uma indentação incorreta pode impedir a execução do programa.

Exemplo incorreto:

if True:
print("Olá, mundo!")

A instrução print() deveria estar dentro do bloco iniciado pelo if.

A mensagem será semelhante a:

IndentationError: expected an indented block

Como corrigir:

if True:
    print("Olá, mundo!")

Agora a instrução está indentada corretamente.

Como evitar esse erro: utilize quatro espaços por nível de indentação e mantenha um padrão consistente. A maioria dos editores de código facilita esse processo, mas é importante compreender por que os espaços são necessários.

A indentação também é essencial em funções, laços de repetição e estruturas condicionais.

3. NameError: nome não definido

O NameError ocorre quando o programa tenta utilizar um nome que não está definido no contexto em que foi acessado.

Isso acontece frequentemente quando uma variável foi escrita incorretamente ou ainda não recebeu um valor.

Exemplo incorreto:

nome = "Tiago"

print(nom)

A variável definida foi nome, mas o código tenta acessar nom.

A mensagem será semelhante a:

NameError: name 'nom' is not defined

Como corrigir:

nome = "Tiago"

print(nome)

Resultado:

Tiago

Como evitar esse erro: confira a grafia dos nomes e lembre-se de que Python diferencia letras maiúsculas de minúsculas. Por exemplo, nome, Nome e NOME são identificadores diferentes.

Também verifique se a variável foi definida antes de ser utilizada e se está acessível naquele contexto.

4. TypeError: operação com tipos incompatíveis

O TypeError aparece quando uma operação ou função recebe um tipo de dado inadequado para o que precisa fazer.

É comum encontrá-lo ao misturar strings, números, listas e outros objetos de maneiras incompatíveis.

Exemplo incorreto:

idade = 25

mensagem = "Minha idade é " + idade

print(mensagem)

O operador + não pode concatenar diretamente uma string com um inteiro.

A mensagem será semelhante a:

TypeError: can only concatenate str (not "int") to str

Como corrigir:

Uma alternativa é converter o número para string:

idade = 25

mensagem = "Minha idade é " + str(idade)

print(mensagem)

Resultado:

Minha idade é 25

Outra alternativa, geralmente mais conveniente, é utilizar uma f-string:

idade = 25

mensagem = f"Minha idade é {idade}"

print(mensagem)

As duas versões corrigidas produzem o resultado esperado.

Como evitar esse erro: identifique o tipo dos valores antes de realizar operações. Quando estiver trabalhando com entradas do usuário, lembre-se de que a função input() retorna uma string, mesmo quando a pessoa digita um número.

Para aprofundar o assunto, consulte Operadores aritméticos em Python.

5. ValueError: valor inválido

O ValueError ocorre quando uma operação recebe um valor de um tipo apropriado, mas não consegue utilizá-lo naquela situação.

Um exemplo frequente é tentar converter um texto que não representa um número inteiro para int.

Exemplo incorreto:

idade = int("vinte")

print(idade)

A função int() não consegue converter a palavra "vinte" em um inteiro.

A mensagem será semelhante a:

ValueError: invalid literal for int() with base 10: 'vinte'

Como corrigir:

Se a intenção é trabalhar com uma idade numérica, utilize um valor que represente um inteiro:

idade = int("20")

print(idade)

Resultado:

20

Se o dado vier do usuário, é melhor validar a entrada e tratar a exceção:

try:
    idade = int(input("Digite sua idade: "))
    print(f"Sua idade é {idade}.")
except ValueError:
    print("Digite uma idade utilizando números inteiros.")

Se a pessoa digitar uma palavra, o programa apresenta uma mensagem compreensível em vez de encerrar a execução por causa dessa exceção não tratada.

Como evitar esse erro: valide os dados recebidos e trate os valores que podem ser inválidos. Não presuma que toda entrada digitada pelo usuário estará no formato esperado.

6. IndexError: índice fora do intervalo

O IndexError ocorre quando você tenta acessar uma posição que não existe em uma sequência, como uma lista ou uma tupla.

Em Python, os índices das listas começam em zero.

Exemplo incorreto:

frutas = ["maçã", "banana", "uva"]

print(frutas[3])

A lista possui três elementos, cujos índices são 0, 1 e 2. Portanto, o índice 3 não existe.

A mensagem será semelhante a:

IndexError: list index out of range

Como corrigir:

Para acessar o terceiro elemento, utilize o índice 2:

frutas = ["maçã", "banana", "uva"]

print(frutas[2])

Resultado:

uva

Outra alternativa é percorrer a lista sem precisar escolher os índices manualmente:

frutas = ["maçã", "banana", "uva"]

for fruta in frutas:
    print(fruta)

Como evitar esse erro: confira o tamanho da sequência antes de acessar uma posição e lembre-se de que o último índice válido de uma lista não vazia é len(lista) - 1.

7. ZeroDivisionError: divisão por zero

O ZeroDivisionError acontece quando o programa tenta dividir um número inteiro ou decimal por zero.

Na matemática, essa operação não está definida.

Exemplo incorreto:

numerador = 10
denominador = 0

resultado = numerador / denominador

print(resultado)

A mensagem será semelhante a:

ZeroDivisionError: division by zero

Como corrigir:

Se o denominador vier de uma variável, verifique se ele é diferente de zero antes de realizar a divisão:

numerador = 10
denominador = 2

if denominador != 0:
    resultado = numerador / denominador
    print(resultado)
else:
    print("Não é possível dividir por zero.")

Resultado:

5.0

Como evitar esse erro: valide os valores antes das operações matemáticas, principalmente quando os dados forem fornecidos pelo usuário ou calculados durante a execução.

8. FileNotFoundError: arquivo não encontrado

O FileNotFoundError ocorre quando o programa tenta acessar um arquivo que não foi encontrado no caminho especificado.

Isso pode acontecer porque o nome está incorreto, o arquivo não existe ou o caminho utilizado não corresponde à localização real.

Exemplo incorreto:

with open("cadastros_inexistentes.txt", "r", encoding="utf-8") as arquivo:
    conteudo = arquivo.read()

print(conteudo)

Se o arquivo não existir no local em que o programa está procurando, será apresentada uma mensagem semelhante a:

FileNotFoundError: [Errno 2] No such file or directory

Como corrigir:

Confira o nome e o caminho do arquivo. Se ele estiver na mesma pasta do programa, crie o arquivo cadastros.txt com algum conteúdo e utilize:

with open("cadastros.txt", "r", encoding="utf-8") as arquivo:
    conteudo = arquivo.read()

print(conteudo)

Para tornar a leitura mais amigável, você também pode tratar a exceção:

try:
    with open("cadastros.txt", "r", encoding="utf-8") as arquivo:
        conteudo = arquivo.read()

    print(conteudo)
except FileNotFoundError:
    print("O arquivo cadastros.txt não foi encontrado.")

Como evitar esse erro: verifique a localização do arquivo, a grafia do nome e o diretório de trabalho do programa. Um caminho relativo, como "cadastros.txt", é interpretado em relação ao diretório de trabalho atual, que nem sempre corresponde à pasta do arquivo Python.

9. ModuleNotFoundError: módulo não encontrado

O ModuleNotFoundError acontece quando o Python tenta importar um módulo que não consegue localizar.

A causa pode ser um nome digitado incorretamente, uma dependência que não foi instalada ou um ambiente Python diferente daquele em que o pacote está disponível.

Exemplo incorreto:

import modulo_que_nao_existe

Como esse módulo não existe no ambiente utilizado, o Python apresentará uma mensagem semelhante a:

ModuleNotFoundError: No module named 'modulo_que_nao_existe'

Como corrigir:

Se você queria utilizar o módulo padrão math, por exemplo, importe o nome correto:

import math

print(math.sqrt(25))

Resultado:

5.0

Se o erro envolver uma biblioteca externa, confira o nome oficial do pacote e se ele está instalado no ambiente em que o programa está sendo executado.

Como evitar esse erro: verifique o nome do módulo, a instalação das dependências e o interpretador Python selecionado no editor. Nem todo módulo precisa ser instalado: a biblioteca padrão já acompanha o Python.

10. KeyError: chave inexistente

O KeyError aparece quando você tenta acessar, em um dicionário, uma chave que não existe.

Diferentemente das listas, os dicionários utilizam chaves para localizar valores.

Exemplo incorreto:

pessoa = {
    "nome": "Tiago",
    "idade": 25
}

print(pessoa["email"])

O dicionário contém as chaves "nome" e "idade", mas não possui "email".

A mensagem será semelhante a:

KeyError: 'email'

Como corrigir:

Se a chave for opcional, utilize o método get():

pessoa = {
    "nome": "Tiago",
    "idade": 25
}

email = pessoa.get("email", "Não informado")

print(email)

Resultado:

Não informado

Se o campo for obrigatório, verifique se a chave existe e investigue por que ela não foi criada ou carregada corretamente.

Como evitar esse erro: confira os nomes das chaves e utilize get() quando um valor puder estar ausente. Não use esse método indiscriminadamente quando a ausência da chave indicar um problema que precisa ser corrigido.

Estudo de caso: como encontrar e corrigir um erro passo a passo

Imagine que você está criando um pequeno programa para cadastrar pessoas e calcular a idade informada.

O código inicial é:

nome = input("Digite seu nome: ")
idade = input("Digite sua idade: ")

ano_nascimento = 2026 - idade

print(f"{nome}, você nasceu em {ano_nascimento}.")

O objetivo parece simples: ler o nome, receber a idade, calcular o ano aproximado de nascimento e apresentar o resultado.

Entretanto, ao executar o programa, você encontrará um TypeError.

Passo 1: leia a mensagem

A mensagem será semelhante a:

TypeError: unsupported operand type(s) for -: 'int' and 'str'

O Python está informando que não consegue realizar a subtração entre um inteiro (int) e uma string (str).

Passo 2: localize a instrução problemática

A linha que merece atenção é:

ano_nascimento = 2026 - idade

A variável idade recebeu o resultado de input(). Essa função retorna uma string, mesmo que a pessoa digite algo como 25.

Portanto, o problema não está na mensagem final nem na variável nome. Está na tentativa de subtrair um texto de um número.

Passo 3: corrija o tipo de dado

Converta a entrada para inteiro:

nome = input("Digite seu nome: ")
idade = int(input("Digite sua idade: "))

ano_nascimento = 2026 - idade

print(f"{nome}, você nasceu em {ano_nascimento}.")

Se o usuário informar Tiago e 25, o resultado será:

Tiago, você nasceu em 2001.

Esse cálculo considera apenas o ano e não leva em conta se a pessoa já fez aniversário no ano utilizado.

Passo 4: pense no que pode dar errado depois

O código corrigido ainda pode apresentar ValueError se o usuário digitar uma palavra no campo da idade.

Uma versão mais preparada para essa situação é:

nome = input("Digite seu nome: ")

try:
    idade = int(input("Digite sua idade: "))

    if idade < 0:
        print("A idade não pode ser negativa.")
    else:
        ano_nascimento = 2026 - idade
        print(f"{nome}, seu ano aproximado de nascimento é {ano_nascimento}.")

except ValueError:
    print("Digite a idade utilizando números inteiros.")

Agora o programa trata entradas que não podem ser convertidas em inteiros e também verifica se a idade é negativa.

Esse exemplo demonstra uma habilidade essencial: corrigir um erro não significa apenas fazer o programa funcionar uma vez. Significa compreender a causa, considerar outras entradas possíveis e tornar o comportamento mais previsível.

Boas práticas para depurar código Python

Depurar é o processo de investigar um programa para entender por que ele não apresenta o comportamento esperado e, quando necessário, corrigir o problema.

Alguns hábitos tornam essa tarefa mais simples.

1. Leia a mensagem antes de alterar o código

Não comece apagando linhas ou modificando várias variáveis. Primeiro, identifique o tipo de erro e leia a descrição.

2. Confira a linha indicada e o contexto

Examine a instrução mencionada no traceback e as linhas relacionadas a ela. O problema pode ter origem em um valor criado anteriormente.

3. Verifique os tipos de dados

Quando houver operações matemáticas, conversões ou concatenações, confirme se os valores possuem os tipos esperados.

4. Teste uma mudança por vez

Faça uma correção pequena e execute novamente o programa. Isso ajuda a identificar o efeito da alteração.

5. Utilize mensagens de depuração

Durante o desenvolvimento, instruções como print() podem ajudar a verificar os valores das variáveis:

idade = input("Digite sua idade: ")

print("Valor recebido:", idade)
print("Tipo recebido:", type(idade))

Esse exemplo permite perceber que input() retorna uma string.

6. Consulte a documentação

Quando não entender uma mensagem, procure o nome exato da exceção na documentação oficial ou em fontes técnicas confiáveis.

A documentação do Python contém explicações sobre erros e exceções, além da lista de exceções internas.

7. Não esconda todos os erros indiscriminadamente

Utilizar try e except pode tornar um programa mais robusto, mas capturar qualquer exceção sem investigar sua causa pode dificultar a identificação de problemas.

Trate as exceções que você espera que possam ocorrer e apresente mensagens úteis para quem utiliza o programa.

Se quiser aprofundar seus conhecimentos sobre a organização e a execução de programas, leia também Entendendo o ponto de entrada de um programa em Python.

Conclusão: aprenda Python com mais confiança

Aprender a corrigir erros em Python é uma parte importante da evolução de qualquer programador. No começo, as mensagens podem parecer difíceis de interpretar, mas elas fornecem pistas sobre o que aconteceu durante a execução do código.

Ao conhecer erros como SyntaxError, IndentationError, NameError, TypeError, ValueError, IndexError, ZeroDivisionError, FileNotFoundError, ModuleNotFoundError e KeyError, você passa a reconhecer situações comuns e a investigar os problemas com mais autonomia.

Lembre-se de que o objetivo não é memorizar todas as mensagens de erro. O mais importante é desenvolver um método: ler, localizar, compreender, corrigir e testar.

Quanto mais você praticar, mais natural será esse processo.

Quer continuar aprendendo programação?

Acesse a página de e-books gratuitos do Entre Bugs e Soluções e encontre materiais para aprofundar seus conhecimentos e avançar nos estudos de Python.