Errores comunes de Python y cómo solucionarlos

Cometer errores es una parte normal de aprender a programar. Python intenta explicar qué ocurrió mediante mensajes y tracebacks, pero al principio esas líneas pueden parecer difíciles de interpretar. La clave no es evitar todos los fallos, sino aprender a leerlos, reproducirlos y corregir la causa real.

Esta guía reúne varios errores comunes de Python, muestra ejemplos incorrectos y explica un proceso de depuración que puedes repetir en cualquier proyecto.

Cómo leer un traceback

Cuando Python detiene un programa, normalmente muestra una cadena de llamadas. Lee primero la última línea: allí aparecen el tipo de excepción y el mensaje. Después revisa las líneas anteriores para localizar el archivo y la instrucción que provocaron el problema.

Traceback (most recent call last):
  File "app.py", line 4, in <module>
    result = 10 / value
ZeroDivisionError: division by zero

La guía oficial de errores y excepciones de Python explica la estructura de estos mensajes. La referencia oficial de excepciones integradas detalla el significado de cada clase.

1. Indentación incorrecta

Python utiliza la indentación para definir bloques. El contenido de una condición, un bucle o una función debe estar desplazado de forma consistente.

age = 20

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

La versión correcta utiliza cuatro espacios:

age = 20

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

Configura el editor para insertar espacios y evita mezclar tabulaciones. La guía de PEP 8 en Python resume las convenciones de formato más importantes.

2. Olvidar que input() devuelve texto

age = input("Edad: ")
next_year = age + 1

El resultado de input() es una cadena. Convierte el valor y controla entradas inválidas:

try:
    age = int(input("Edad: "))
    print(f"El próximo año tendrás {age + 1}.")
except ValueError:
    print("Introduce un número entero.")

El tutorial de input() en Python explica validación, menús y funciones reutilizables.

3. Elegir una estructura inadecuada

Una lista conserva el orden, un conjunto evita duplicados y un diccionario relaciona claves con valores. Elegir la estructura correcta simplifica el código.

blocked_users = {"ana", "leo", "mia"}

if "leo" in blocked_users:
    print("Usuario bloqueado")

Para información etiquetada, utiliza un diccionario:

product = {
    "name": "Teclado",
    "price": 89.90,
    "stock": 12,
}

La comparación de listas, tuplas, sets y diccionarios ayuda a decidir qué colección utilizar.

4. Capturar todas las excepciones

try:
    value = int(user_text)
except:
    pass

Este patrón oculta información importante. Captura solamente el error esperado:

try:
    value = int(user_text)
except ValueError as error:
    print(f"Entero inválido: {error}")

La guía de try y except en Python explica else, finally, excepciones propias y encadenamiento.

5. Crear un script demasiado largo

Cuando toda la lógica permanece en el nivel principal, aparecen repeticiones y variables difíciles de seguir. Divide el proceso en funciones pequeñas.

def read_age() -> int:
    while True:
        try:
            return int(input("Edad: "))
        except ValueError:
            print("Introduce un entero.")


def greet(name: str, age: int) -> str:
    return f"Hola {name}, tienes {age} años."

Consulta la guía de funciones en Python para aprender parámetros, retornos y buenas prácticas.

6. Instalar paquetes globalmente

Dos proyectos pueden necesitar versiones diferentes de una biblioteca. Crea un entorno aislado:

python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS o Linux
source .venv/bin/activate

python -m pip install requests

La guía de venv en Python explica cómo evitar instalar en el intérprete equivocado.

7. Nombres y comentarios poco claros

def c(a, b):
    return a * b * 0.15

Una versión más clara comunica la intención:

TAX_RATE = 0.15


def calculate_tax(price: float, quantity: int) -> float:
    """Calculate tax for a product order."""
    subtotal = price * quantity
    return subtotal * TAX_RATE

Los artículos sobre comentarios en Python y docstrings ayudan a documentar sin llenar el código de ruido.

Excepciones frecuentes

NameError

El nombre no existe en el ámbito actual. Revisa ortografía y orden de ejecución.

total = 25
print(totla)

IndexError

El índice está fuera de la secuencia:

colors = ["azul", "verde"]
print(colors[2])

KeyError

La clave no existe en el diccionario. Cuando la ausencia sea normal, utiliza get().

user = {"name": "Sam"}
email = user.get("email")

AttributeError

El objeto no dispone del método solicitado. Comprueba su tipo con type().

number = 10
number.append(5)

ModuleNotFoundError

Puede significar que el paquete no está instalado en el entorno activo o que un archivo local está ocultando la biblioteca real. Verifica sys.executable, el nombre del archivo y el entorno seleccionado.

Proceso de depuración recomendado

1. Lee el traceback completo.
2. Abre exactamente la línea mencionada.
3. Comprueba el valor y el tipo de cada variable.
4. Reduce el problema a un ejemplo pequeño.
5. Consulta la documentación oficial.
6. Cambia una sola cosa cada vez.
7. Añade una prueba que reproduzca el fallo corregido.

Para regresiones, utiliza el tutorial de Pytest para principiantes.

Depurar con print() y logging

Un mensaje temporal puede mostrar valores y rutas de ejecución:

def calculate_average(values):
    print(f"DEBUG {values=}")
    total = sum(values)
    return total / len(values)

El especificador de depuración de las f-strings se explica en depurar Python con f-strings. En aplicaciones duraderas, sustituye mensajes dispersos por logging y evita registrar contraseñas o datos privados.

Errores al intentar corregir errores

• Cambiar muchas líneas a la vez.
• Reinstalar Python antes de leer el mensaje.
• Ocultar todo con un except Exception.
• Copiar una solución de otra versión sin comprobarla.
• Ignorar datos de entrada que reproducen el problema.
• Eliminar una prueba que falla en lugar de corregir la causa.

Conclusión

Los errores comunes de Python se vuelven manejables cuando lees el traceback, verificas tipos y valores, reduces el caso y consultas fuentes oficiales. Utiliza una indentación consistente, convierte entradas externas, elige estructuras adecuadas, captura excepciones específicas, organiza el código en funciones y trabaja con entornos aislados. Cada error bien comprendido mejora tu capacidad para resolver el siguiente.