Cómo corregir errores en Python: 10 errores comunes

Si estás aprendiendo Python, probablemente te hayas encontrado con una situación frustrante: ejecutaste tu código, esperabas ver el resultado y, en su lugar, apareció un mensaje de error lleno de palabras en inglés, nombres desconocidos y números de línea.

Al principio, esto puede parecer complicado. Lees el mensaje, intentas entender qué ha ocurrido y, a veces, terminas cambiando varias partes del código sin saber exactamente dónde está el problema.

Esta dificultad es común entre los principiantes. Aprender a programar no consiste únicamente en escribir instrucciones correctamente, sino también en desarrollar la capacidad de identificar problemas, interpretar mensajes y encontrar soluciones.

En esta guía, aprenderás cómo corregir errores en Python, conocerás diez errores comunes y descubrirás qué hacer cuando aparecen. Para cada situación, veremos un ejemplo incorrecto, el mensaje de error esperado, la causa del problema y una versión corregida del código.

También aprenderás a interpretar un traceback y recorrerás un caso práctico ilustrativo que muestra cómo investigar un error paso a paso.

¿Por qué se producen errores en Python?

Un programa está formado por instrucciones que deben seguir determinadas reglas. Cuando se incumple alguna de ellas o el programa encuentra una situación que no puede procesar, puede producirse un error.

Esto puede ocurrir por diferentes motivos:

• Una palabra está mal escrita.

• Se utiliza una variable antes de definirla.

• Se realiza una operación con tipos de datos incompatibles.

• Un índice o una clave no existe.

• No se encuentra un archivo o módulo.

• Se realiza una operación matemática no válida.

En Python, es importante distinguir entre dos categorías de problemas: los errores de sintaxis y las excepciones.

Los errores de sintaxis se producen cuando el intérprete no puede analizar correctamente el código. Las excepciones, por otro lado, suelen aparecer durante la ejecución, cuando una operación encuentra una situación problemática.

Comprender esta diferencia te ayudará a elegir el enfoque adecuado para investigar cada situación.

Cómo interpretar un mensaje de error en Python

Antes de explorar los diez errores, conviene aprender a leer la información que muestra Python cuando algo sale mal.

Imagina el siguiente programa:

name = "Tiago"
age = "25"

result = name + age + 5

print(result)

Al ejecutar este código, obtendrás un TypeError, porque la expresión intenta sumar una cadena de texto a un número entero.

El mensaje será parecido a este:

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

Al principio, este mensaje puede parecer complicado, pero contiene información útil.

¿Qué es un traceback?

Cuando una excepción no se gestiona, Python suele mostrar un traceback que indica la ruta de ejecución que condujo hasta el punto en el que se produjo el problema.

Un traceback suele contener:

• El nombre del archivo que se está ejecutando.

• El número de línea asociado al problema.

• El fragmento de código correspondiente, cuando está disponible.

• El tipo de excepción.

• Una descripción de lo que ha ocurrido.

La última línea suele ser un buen punto de partida, ya que proporciona el nombre de la excepción y una breve explicación.

Cómo encontrar la línea que contiene el error

Busca una indicación similar a esta:

File "program.py", line 4

Esto significa que Python está señalando la línea 4 del archivo program.py.

Sin embargo, la línea indicada no siempre contiene el punto exacto que debes corregir. Por ejemplo, un error de sintaxis puede detectarse en un lugar diferente de aquel en el que debería haberse incluido el símbolo que falta.

Lee el mensaje completo, examina la línea indicada y revisa también las instrucciones anteriores.

Qué hacer cuando no entiendes el mensaje

Sigue este procedimiento:

1. Identifica el nombre del error, como TypeError o NameError.

2. Lee la descripción que aparece después del nombre.

3. Localiza la línea indicada en el traceback.

4. Comprueba los valores, las variables y las operaciones involucradas.

5. Realiza un pequeño cambio y vuelve a ejecutar el programa.

Evita modificar varias partes del código al mismo tiempo. Si cambias una sola cosa cada vez, será más fácil identificar qué modificación ha solucionado el problema.

Si quieres una introducción más detallada al lenguaje, consulta el artículo ¿Qué es Python?.

Los 10 errores más comunes en Python y cómo solucionarlos

Los siguientes ejemplos utilizan características disponibles en Python 3.12 o versiones posteriores y pueden adaptarse a distintos editores y entornos de ejecución.

1. SyntaxError: error de sintaxis

Un SyntaxError se produce cuando el código no sigue la sintaxis que espera Python.

Puede deberse a paréntesis que faltan, comillas sin cerrar, dos puntos olvidados o palabras clave utilizadas incorrectamente.

Ejemplo incorrecto:

age = 25

if age >= 18
    print("Adult")

En este caso, faltan los dos puntos (:) al final de la condición.

El mensaje será parecido a este:

SyntaxError: expected ':'

Cómo solucionarlo:

age = 25

if age >= 18:
    print("Adult")

Ahora el código tiene una sintaxis correcta e imprime Adult.

Cómo evitar este error: Comprueba que haya dos puntos después de if, elif, else, for, while, def y otras estructuras que requieren este símbolo. Asegúrate también de cerrar correctamente los paréntesis, los corchetes y las comillas.

Si quieres repasar las expresiones y los operadores que se utilizan en estas condiciones, consulta Expresiones en Python.

2. IndentationError: indentación incorrecta

Python utiliza la indentación, es decir, los espacios al comienzo de las líneas, para definir bloques de código.

Una indentación incorrecta puede impedir que un programa se ejecute.

Ejemplo incorrecto:

if True:
print("Hello, world!")

La instrucción print() debe estar dentro del bloque iniciado por la instrucción if.

El mensaje será parecido a este:

IndentationError: expected an indented block

Cómo solucionarlo:

if True:
    print("Hello, world!")

Ahora la instrucción tiene la indentación correcta.

Cómo evitar este error: Utiliza cuatro espacios por nivel de indentación y mantén un patrón coherente. La mayoría de los editores de código facilitan este proceso, pero es importante comprender por qué la indentación es necesaria.

La indentación también es esencial en las funciones, los bucles y las estructuras condicionales.

3. NameError: nombre no definido

Un NameError se produce cuando un programa intenta utilizar un nombre que no se ha definido en el contexto en el que se está utilizando.

Esto suele ocurrir cuando el nombre de una variable está mal escrito o cuando todavía no se le ha asignado un valor.

Ejemplo incorrecto:

name = "Tiago"

print(nam)

La variable definida es name, pero el código intenta acceder a nam.

El mensaje será parecido a este:

NameError: name 'nam' is not defined

Cómo solucionarlo:

name = "Tiago"

print(name)

Salida:

Tiago

Cómo evitar este error: Comprueba la escritura de los nombres y recuerda que Python distingue entre mayúsculas y minúsculas. Por ejemplo, name, Name y NAME son identificadores diferentes.

Comprueba también que la variable se haya definido antes de utilizarla y que esté disponible en el contexto actual.

4. TypeError: operación con tipos incompatibles

Un TypeError se produce cuando una operación o función recibe un tipo de dato inadecuado para la tarea que debe realizar.

Este error es habitual cuando se combinan cadenas de texto, números, listas y otros objetos de formas incompatibles.

Ejemplo incorrecto:

age = 25

message = "My age is " + age

print(message)

El operador + no puede concatenar directamente una cadena de texto con un número entero.

El mensaje será parecido a este:

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

Cómo solucionarlo:

Una opción es convertir el número en una cadena de texto:

age = 25

message = "My age is " + str(age)

print(message)

Salida:

My age is 25

Otra alternativa, generalmente más cómoda, es utilizar una f-string:

age = 25

message = f"My age is {age}"

print(message)

Ambas versiones corregidas producen el resultado esperado.

Cómo evitar este error: Identifica el tipo de cada valor antes de realizar operaciones. Cuando trabajes con datos introducidos por el usuario, recuerda que la función input() devuelve una cadena de texto, incluso cuando el usuario introduce un número.

Para obtener más información, consulta Operadores aritméticos en Python.

5. ValueError: valor no válido

Un ValueError se produce cuando una operación recibe un valor del tipo adecuado, pero no puede utilizarlo en esa situación concreta.

Un ejemplo habitual es intentar convertir en un int un texto que no representa un número entero.

Ejemplo incorrecto:

age = int("twenty")

print(age)

La función int() no puede convertir la palabra "twenty" en un número entero.

El mensaje será parecido a este:

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

Cómo solucionarlo:

Si el objetivo es trabajar con una edad numérica, utiliza un valor que represente un número entero:

age = int("20")

print(age)

Salida:

20

Si el dato procede del usuario, es preferible validar la entrada y gestionar la excepción:

try:
    age = int(input("Enter your age: "))
    print(f"Your age is {age}.")
except ValueError:
    print("Please enter your age as a whole number.")

Si el usuario introduce una palabra, el programa muestra un mensaje comprensible en lugar de finalizar debido a una excepción no gestionada.

Cómo evitar este error: Valida los datos recibidos y gestiona los valores que puedan ser incorrectos. No des por hecho que todas las entradas del usuario tendrán el formato esperado.

6. IndexError: índice fuera de rango

Un IndexError se produce cuando intentas acceder a una posición que no existe en una secuencia, como una lista o una tupla.

En Python, los índices de las listas comienzan en cero.

Ejemplo incorrecto:

fruits = ["apple", "banana", "grape"]

print(fruits[3])

La lista contiene tres elementos, cuyos índices son 0, 1 y 2. Por tanto, el índice 3 no existe.

El mensaje será parecido a este:

IndexError: list index out of range

Cómo solucionarlo:

Para acceder al tercer elemento, utiliza el índice 2:

fruits = ["apple", "banana", "grape"]

print(fruits[2])

Salida:

grape

Otra opción es recorrer la lista sin seleccionar los índices manualmente:

fruits = ["apple", "banana", "grape"]

for fruit in fruits:
    print(fruit)

Cómo evitar este error: Comprueba la longitud de la secuencia antes de acceder a una posición y recuerda que el último índice válido de una lista no vacía es len(list) - 1.

7. ZeroDivisionError: división entre cero

Un ZeroDivisionError se produce cuando un programa intenta dividir un número entero o de punto flotante entre cero.

En matemáticas, esta operación no está definida.

Ejemplo incorrecto:

numerator = 10
denominator = 0

result = numerator / denominator

print(result)

El mensaje será parecido a este:

ZeroDivisionError: division by zero

Cómo solucionarlo:

Si el denominador procede de una variable, comprueba que no sea cero antes de realizar la división:

numerator = 10
denominator = 2

if denominator != 0:
    result = numerator / denominator
    print(result)
else:
    print("Division by zero is not possible.")

Salida:

5.0

Cómo evitar este error: Valida los valores antes de realizar operaciones matemáticas, especialmente cuando los datos los proporciona el usuario o se calculan durante la ejecución.

8. FileNotFoundError: archivo no encontrado

Un FileNotFoundError se produce cuando un programa intenta acceder a un archivo que no se encuentra en la ruta especificada.

Esto puede ocurrir porque el nombre del archivo es incorrecto, el archivo no existe o la ruta no coincide con su ubicación real.

Ejemplo incorrecto:

with open("nonexistent_records.txt", "r", encoding="utf-8") as file:
    content = file.read()

print(content)

Si el archivo no existe en la ubicación en la que el programa lo busca, aparecerá un mensaje parecido a este:

FileNotFoundError: [Errno 2] No such file or directory

Cómo solucionarlo:

Comprueba el nombre y la ruta del archivo. Si debería estar en el mismo directorio que el programa, crea un archivo llamado records.txt con algo de contenido y utiliza:

with open("records.txt", "r", encoding="utf-8") as file:
    content = file.read()

print(content)

Para que el programa resulte más fácil de utilizar, también puedes gestionar la excepción:

try:
    with open("records.txt", "r", encoding="utf-8") as file:
        content = file.read()

    print(content)
except FileNotFoundError:
    print("The records.txt file was not found.")

Cómo evitar este error: Comprueba la ubicación del archivo, la escritura de su nombre y el directorio de trabajo del programa. Una ruta relativa como "records.txt" se interpreta en relación con el directorio de trabajo actual, que no siempre coincide con el directorio que contiene el archivo Python.

9. ModuleNotFoundError: módulo no encontrado

Un ModuleNotFoundError se produce cuando Python intenta importar un módulo que no puede localizar.

La causa puede ser un nombre mal escrito, una dependencia que no está instalada o un entorno de Python diferente de aquel en el que está disponible el paquete.

Ejemplo incorrecto:

import module_that_does_not_exist

Como este módulo no existe en el entorno actual, Python mostrará un mensaje parecido a este:

ModuleNotFoundError: No module named 'module_that_does_not_exist'

Cómo solucionarlo:

Si, por ejemplo, querías utilizar el módulo estándar math, importa el nombre correcto:

import math

print(math.sqrt(25))

Salida:

5.0

Si el error afecta a una biblioteca externa, comprueba el nombre oficial del paquete y si está instalado en el entorno en el que se ejecuta el programa.

Cómo evitar este error: Comprueba el nombre del módulo, la instalación de las dependencias y el intérprete de Python seleccionado en tu editor. No todos los módulos necesitan instalarse: la biblioteca estándar ya viene incluida con Python.

10. KeyError: clave inexistente en un diccionario

Un KeyError se produce cuando intentas acceder a una clave de un diccionario que no existe.

A diferencia de las listas, los diccionarios utilizan claves para localizar los valores.

Ejemplo incorrecto:

person = {
    "name": "Tiago",
    "age": 25
}

print(person["email"])

El diccionario contiene las claves "name" y "age", pero no contiene "email".

El mensaje será parecido a este:

KeyError: 'email'

Cómo solucionarlo:

Si la clave es opcional, utiliza el método get():

person = {
    "name": "Tiago",
    "age": 25
}

email = person.get("email", "Not provided")

print(email)

Salida:

Not provided

Si el campo es obligatorio, comprueba si existe la clave e investiga por qué no se creó o no se cargó correctamente.

Cómo evitar este error: Comprueba los nombres de las claves y utiliza get() cuando un valor pueda faltar. No utilices este método indiscriminadamente cuando la ausencia de una clave indique un problema que deba corregirse.

Caso práctico: cómo encontrar y corregir un error paso a paso

Imagina que estás creando un pequeño programa para registrar personas y calcular su año de nacimiento aproximado a partir de su edad declarada.

El código inicial es el siguiente:

name = input("Enter your name: ")
age = input("Enter your age: ")

birth_year = 2026 - age

print(f"{name}, you were born in {birth_year}.")

El objetivo parece sencillo: leer el nombre, recibir la edad, calcular el año de nacimiento aproximado y mostrar el resultado.

Sin embargo, al ejecutar el programa, aparecerá un TypeError.

Paso 1: lee el mensaje de error

El mensaje será parecido a este:

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

Python te está indicando que no puede restar una cadena de texto (str) a un número entero (int).

Paso 2: localiza la instrucción problemática

La línea que debes revisar es:

birth_year = 2026 - age

La variable age recibió el resultado de input(). Esta función devuelve una cadena de texto, incluso cuando el usuario introduce algo como 25.

Por tanto, el problema no está en el mensaje final ni en la variable name. El problema es el intento de restar texto a un número.

Paso 3: corrige el tipo de dato

Convierte la entrada en un número entero:

name = input("Enter your name: ")
age = int(input("Enter your age: "))

birth_year = 2026 - age

print(f"{name}, you were born in {birth_year}.")

Si el usuario introduce Tiago y 25, el resultado será:

Tiago, you were born in 2001.

Este cálculo solo tiene en cuenta el año y no contempla si la persona ya ha cumplido años durante el año de referencia.

Paso 4: considera qué podría fallar después

El código corregido todavía puede generar un ValueError si el usuario introduce una palabra en el campo de la edad.

Una versión mejor preparada para esta situación es:

name = input("Enter your name: ")

try:
    age = int(input("Enter your age: "))

    if age < 0:
        print("Age cannot be negative.")
    else:
        birth_year = 2026 - age
        print(f"{name}, your approximate birth year is {birth_year}.")

except ValueError:
    print("Please enter your age as a whole number.")

Ahora, el programa gestiona las entradas que no se pueden convertir en números enteros y también comprueba si la edad es negativa.

Este ejemplo demuestra una habilidad esencial: corregir un error no consiste simplemente en conseguir que el programa funcione una vez. Significa comprender la causa, considerar otras entradas posibles y hacer que el comportamiento del programa sea más predecible.

Buenas prácticas para depurar código Python

La depuración es el proceso de investigar un programa para comprender por qué no se comporta como se espera y, cuando sea necesario, corregir el problema.

Algunos hábitos facilitan esta tarea.

1. Lee el mensaje de error antes de modificar el código

No empieces eliminando líneas ni modificando varias variables. Primero, identifica el tipo de error y lee su descripción.

2. Comprueba la línea indicada y su contexto

Examina la instrucción mencionada en el traceback y las líneas relacionadas. El problema puede tener su origen en un valor creado anteriormente.

3. Comprueba los tipos de datos

Cuando trabajes con operaciones matemáticas, conversiones o concatenaciones, confirma que los valores tengan los tipos esperados.

4. Prueba un cambio cada vez

Realiza una pequeña corrección y vuelve a ejecutar el programa. Esto te ayudará a identificar el efecto del cambio.

5. Utiliza mensajes de depuración

Durante el desarrollo, instrucciones como print() pueden ayudarte a inspeccionar los valores de las variables:

age = input("Enter your age: ")

print("Received value:", age)
print("Received type:", type(age))

Este ejemplo permite comprobar que input() devuelve una cadena de texto.

6. Consulta la documentación

Cuando no entiendas un mensaje, busca el nombre exacto de la excepción en la documentación oficial o en otras fuentes técnicas fiables.

La documentación de Python contiene explicaciones sobre errores y excepciones, así como una lista de excepciones integradas.

7. No ocultes indiscriminadamente todos los errores

Utilizar try y except puede hacer que un programa sea más robusto, pero capturar todas las excepciones sin investigar su causa puede dificultar la identificación de los problemas.

Gestiona las excepciones que esperas que puedan producirse y proporciona mensajes útiles a las personas que utilizan el programa.

Si quieres profundizar en la organización y ejecución de los programas, lee también Cómo entender el punto de entrada de un programa Python.

Conclusión: aprende Python con mayor confianza

Aprender a corregir errores en Python es una parte importante del desarrollo de cualquier programador. Al principio, los mensajes de error pueden parecer difíciles de interpretar, pero proporcionan pistas sobre lo que ha ocurrido durante la ejecución del código.

Al aprender a reconocer errores como SyntaxError, IndentationError, NameError, TypeError, ValueError, IndexError, ZeroDivisionError, FileNotFoundError, ModuleNotFoundError y KeyError, mejorarás tu capacidad para reconocer situaciones habituales e investigar problemas de forma autónoma.

Recuerda que el objetivo no es memorizar todos los mensajes de error. Lo más importante es desarrollar un método: leer, localizar, comprender, corregir y probar.

Cuanto más practiques, más natural te resultará este proceso.

¿Quieres seguir aprendiendo programación?

Visita la página de libros electrónicos gratuitos de Entre Bugs e Soluções y encuentra recursos para ampliar tus conocimientos y continuar estudiando Python.