Leer mensajes de error y tracebacks con calma

Un solo artículo mal escrito, cofee, detiene el programa de facturación de esta lección con un informe de once líneas, y la errata se encuentra en segundos en cuanto sabes qué línea del informe leer primero.

Cuando un programa falla, Python se detiene e imprime un tracebacktraceback: El informe que imprime Python cuando una excepción termina un programa: las llamadas que llevaron a la línea que falla, la más antigua primero, y en la última línea el tipo y el mensaje de la excepción. Más en “Manejar excepciones con try y except” (en inglés). Los primeros asustan, pero un traceback es un informe preciso con tres partes: qué salió mal, la línea donde ocurrió y la cadena de llamadas que llevó hasta allí. Leerlo en ese orden, de abajo arriba, es la forma más rápida de encontrar la mayoría de los errores.

Léelo de abajo arriba

Este programa suma dos cuentas. La primera funciona; la segunda tiene una errata en su pedido:

prices = {"tea": 30, "toast": 45, "coffee": 60}


def line_total(item, quantity):
    return prices[item] * quantity


def bill(order):
    total = 0
    for item, quantity in order:
        total += line_total(item, quantity)
    return total


print("First bill:", bill([("tea", 2), ("toast", 1)]))
print("Second bill:", bill([("tea", 1), ("cofee", 2)]))

First bill: 105

Traceback (most recent call last):
  File "bill.py", line 16, in <module>
    print("Second bill:", bill([("tea", 1), ("cofee", 2)]))
                          ~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "bill.py", line 11, in bill
    total += line_total(item, quantity)
             ~~~~~~~~~~^^^^^^^^^^^^^^^^
  File "bill.py", line 5, in line_total
    return prices[item] * quantity
           ~~~~~~^^^^^^
KeyError: 'cofee'

Empieza por la última línea y sube:

1. La última línea nombra la excepción y da su mensaje. KeyError: 'cofee' dice que se pidió a un diccionario una clave que no tiene, y el mensaje es esa clave.
2. El marco justo encima muestra dónde ocurrió: File "bill.py", line 5, in line_total y después la propia línea. Las marcas ~ y ^ debajo señalan la parte de la línea que falló, la consulta prices[item].
3. Cada marco más arriba es una llamada que llevó hasta allí. bill() llamó a line_total() en la línea 11, y el nivel superior del archivo (<module>) llamó a bill() en la línea 16. “Most recent call last” (la llamada más reciente, la última) significa que los marcos van desde la primera llamada hasta la línea que falló.

Cada bloque de dos o tres líneas del informe es un marcomarco: El registro de una llamada a una función que no ha terminado: sus variables locales y el punto donde continuar cuando vuelva la llamada que espera. Más en “Recursión, la pila de llamadas y sus límites” (en inglés), una llamada que no había terminado cuando ocurrió el error. Recorre las llamadas de la segunda cuenta y el camino del error de vuelta por ellas:

La línea que falló no siempre es la que hay que arreglar. A line_total() no le pasa nada: recibió un valor incorrecto. Sigue leyendo hacia arriba hasta llegar a la línea de donde vino el valor incorrecto, aquí el pedido de la línea 16. Fíjate también en que la primera cuenta se imprimió: todo lo anterior a la línea que falla se ejecutó con normalidad. Pulsa Editar, corrige cofee en la línea 16 y ejecútalo: se imprimen las dos cuentas, y la segunda es 150.

Cuando los marcos que fallan no son tu código

Si pasas algo incorrecto a una función de la biblioteca estándar o de un paquete, los últimos marcos están dentro de los propios archivos de esa función:

import json

settings_text = "{'theme': 'dark'}"
settings = json.loads(settings_text)
print("Theme:", settings["theme"])

Traceback (most recent call last):
  File "bad_json.py", line 4, in <module>
    settings = json.loads(settings_text)
  File "…/lib/python3.14/json/__init__.py", line 352, in loads
    return _default_decoder.decode(s)
           ~~~~~~~~~~~~~~~~~~~~~~~^^^
  File "…/lib/python3.14/json/decoder.py", line 345, in decode
    obj, end = self.raw_decode(s, idx=_w(s, 0).end())
               ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
  File "…/lib/python3.14/json/decoder.py", line 361, in raw_decode
    obj, end = self.scan_once(s, idx)
               ~~~~~~~~~~~~~~^^^^^^^^
json.decoder.JSONDecodeError: Expecting property name enclosed in double quotes: line 1 column 2 (char 1)

Los marcos bajo …/lib/python3.14/json/ pertenecen al módulo json de Python (… representa la carpeta en la que está instalado Python, que cambia de una computadora a otra). No busques un error ahí. Busca el último marco que está en tu propio archivo, la línea 4, donde se llamó a json.loads(), y comprueba qué le diste. El mensaje dice el resto: JSON necesita comillas dobles alrededor de los nombres, así que el texto debería haber sido '{"theme": "dark"}'.

Un SyntaxError significa que no se ejecutó nada

Python lee un archivo entero antes de ejecutar nada de él. Cuando la gramática está mal, informa de un SyntaxError y no ejecuta nada en absoluto, ni siquiera las líneas de encima del error:

print("This line never runs")


def greeting(name):
    retrun "Hello, " + name


print(greeting("Asha"))

  File "typo_keyword.py", line 5
    retrun "Hello, " + name
    ^^^^^^
SyntaxError: invalid syntax. Did you mean 'return'?

Esta vez no hay línea “Traceback (most recent call last)”, porque no hubo ninguna llamada: el archivo nunca empezó. La primera línea, un print(), no imprimió nada por la misma razón. Pulsa Editar, corrige retrun por return y ejecútalo: ahora se ejecutan las dos llamadas a print(), incluida la primera.

A veces la línea que muestra Python parece perfectamente correcta. Entonces la causa suele estar antes, a menudo un corchete o unas comillas que se abrieron y nunca se cerraron. Python señala dónde se abrieron:

marks = [72, 88, 95
print(sum(marks) / len(marks))

  File "unclosed.py", line 1
    marks = [72, 88, 95
            ^
SyntaxError: '[' was never closed

La lista de la línea 1 nunca recibe su ]. Dentro de unos corchetes Python sigue leyendo las líneas siguientes, así que llega al final del archivo todavía dentro de la lista, e informa de la línea en la que empezó la lista. IndentationError, para líneas con una sangría que no encaja con los bloques de alrededor, también es un tipo de SyntaxError y se informa igual, antes de que se ejecute nada.

Cada excepción común señala un tipo de error

Cada una de estas ocho líneas comete un error distinto. El programa las ejecuta una a una e imprime la última línea de cada traceback, así que ves los mensajes exactos de esta versión de Python:

import traceback

# Eight one-line mistakes. exec() runs each line as a tiny program and the error is caught,
# so you see the last line of every traceback, exactly as Python prints it.
mistakes = [
    "print(scroe)",
    '"3" + 4',
    'int("three")',
    "[10, 20, 30][3]",
    '{"tea": 30}["coffee"]',
    '"text".uper()',
    "1 / 0",
    "import numpyy",
]
for code in mistakes:
    try:
        exec(code)
    except Exception as error:
        last_line = traceback.format_exception_only(error)[-1].strip()
        print(f"{code:<24}{last_line}")

print(scroe)            NameError: name 'scroe' is not defined
"3" + 4                 TypeError: can only concatenate str (not "int") to str
int("three")            ValueError: invalid literal for int() with base 10: 'three'
[10, 20, 30][3]         IndexError: list index out of range
{"tea": 30}["coffee"]   KeyError: 'coffee'
"text".uper()           AttributeError: 'str' object has no attribute 'uper'. Did you mean: 'upper'?
1 / 0                   ZeroDivisionError: division by zero
import numpyy           ModuleNotFoundError: No module named 'numpyy'

Cuando un nombre o un atributo está mal escrito y existe algo parecido, Python añade Did you mean …?, como para uper arriba. Pulsa Editar, añade a la lista un error tuyo, como '"5" * "2"', y ejecútalo para ver su mensaje. Lo que suele significar cada error, y dónde mirar primero:

Un error común: un archivo con el nombre de un módulo

Ponle a tu archivo el nombre de un módulo que importas, como random.py, y Python importa tu archivo en lugar del módulo. Python 3.13 y posteriores lo notan y lo dicen:

import random

print("Your dice roll:", random.randint(1, 6))

Traceback (most recent call last):
  File "random.py", line 1, in <module>
    import random
  File "random.py", line 3, in <module>
    print("Your dice roll:", random.randint(1, 6))
                             ^^^^^^^^^^^^^^
AttributeError: module 'random' has no attribute 'randint' (consider renaming 'random.py' since it has the same name as the standard library module named 'random' and prevents importing that standard library module)

El script se importa a sí mismo como random, así que random.randint no existe. El mensaje incluso nombra el archivo que hay que renombrar: llámalo dice.py y import random vuelve a encontrar el módulo de la biblioteca estándar. Python 3.12 y anteriores informan del mismo error solo como un “partially initialized module” (módulo inicializado a medias) y una posible importación circular.

Los mensajes de Python se hicieron más claros, versión a versión

Python 3.14 también mejoró otros mensajes. Usar una lista como clave de un diccionario falla, como antes, porque las claves deben ser hashableshashable: Un valor que puede ser una clave de un dict o un elemento de un set, porque su hash nunca cambia mientras existe: los números, las cadenas y las tuplas de valores hashables son hashables; las listas, los dicts y los sets no. Más en “functools: cache, partial, reduce y más” (en inglés), y una lista, que puede cambiar, no lo es; pero ahora el mensaje dice lo que intentabas hacer:

stock = {}
stock[["tea", "toast"]] = 2

Traceback (most recent call last):
  File "unhashable.py", line 2, in <module>
    stock[["tea", "toast"]] = 2
    ~~~~~^^^^^^^^^^^^^^^^^^
TypeError: cannot use 'list' as a dict key (unhashable type: 'list')

Cada versión con novedades desde la 3.10 ha añadido mensajes como estos, así que el mismo error se lee de otra forma en un Python más antiguo. Recorre lo que cambió cada versión:

En el Python que ejecutas, los mensajes más nuevos son la ayuda que recibes. En uno más antiguo, como el Python de un servidor, espera solo la redacción antigua, y lee tú mismo la parte marcada de la línea.

Cuando te atascas: lee, imprime, reduce y después busca

1. Lee la última línea despacio y busca la excepción en la página Built-in Exceptions (excepciones integradas) de la documentación de Python. En el intérprete, help() muestra la documentación de una función, un tipo o un módulo, y issubclass() te dice a qué tipo de error más amplio pertenece una excepción:

   >>> help(len)
   Help on built-in function len in module builtins:
   
   len(obj, /)
       Return the number of items in a container.
   
   >>> issubclass(KeyError, LookupError)
   True
   >>> issubclass(ModuleNotFoundError, ImportError)
   True

   Esta sesión se reprodujo con Python 3.14.8 en macOS 26 arm64 e imprimió exactamente lo que se muestra.

2. Imprime lo que tienes. Justo encima de la línea que falla, añade print(repr(value), type(value)) para los valores que usa. La mayoría de las sorpresas son un valor de otro tipo, o un texto con un espacio que no se ve.

3. Haz un ejemplo mínimo. Copia el programa y borra todo lo que no hace falta para que ocurra el error, hasta que queden unas pocas líneas. A menudo encuentras el error por el camino; si no, esas pocas líneas son lo que enseñas cuando pides ayuda.

4. Busca la última línea, sin los nombres y los valores propios de tu programa.

Recorre los cuatro pasos sobre el KeyError de bill.py:

Este es el paso 2 con un valor leído de un archivo: print() muestra el artículo como coffee, y solo repr() muestra el espacio de detrás que hace fallar la consulta:

prices = {"tea": 30, "coffee": 60}
item = "coffee "  # read from a file, with a space at the end
print(item)
print(repr(item), type(item))
print(item in prices)

coffee 
'coffee ' <class 'str'>
False

Y este es el paso 3 con bill.py: las dos líneas que siguen lanzando el mismo error forman un ejemplo mínimoEl programa más pequeño que todavía muestra un error, hecho borrando todo lo que el error no necesita. Hacer uno a menudo encuentra el error; si no, es lo que enseñas cuando pides ayuda.:

prices = {"coffee": 60}
print(prices["cofee"])

Traceback (most recent call last):
  File "minimal.py", line 2, in <module>
    print(prices["cofee"])
          ~~~~~~^^^^^^^^^
KeyError: 'cofee'

Practica: arregla una cuenta leyendo sus tracebacks

bill_total() suma un pedido escrito como líneas de texto, y su código inicial falla con dos tracebacks distintos. Ejecuta las pruebas de ejemplo, lee cada traceback de abajo arriba y arregla cada valor incorrecto donde se origina:

PRICES = {"tea": 30, "toast": 45, "coffee": 60}


def bill_total(lines):
    """Add up an order given as lines of text such as "tea,2"."""
    total = 0
    for line in lines:
        item, quantity = line.split(",")
        total += PRICES[item] * quantity
    return total

from bill import bill_total


def test_two_lines():
    """adds up each item's price times its quantity"""
    assert bill_total(["tea,2", "toast,1"]) == 105


def test_spaces():
    """allows spaces around the item and the quantity"""
    assert bill_total([" coffee , 2"]) == 120
    assert bill_total(["tea , 1", " toast,2 "]) == 120


def test_empty_order():
    """an empty order costs nothing"""
    assert bill_total([]) == 0

Después resuelve las preguntas sobre las cinco ideas, de leer marcos a desatascarte. Una idea que falles vuelve a preguntarse primero, y cada opción te dice qué acertó o en qué falló:

Preguntas de entrevista

Calentamiento (júnior): ¿cómo se lee un traceback de Python?

De abajo arriba. La última línea nombra la excepción y su mensaje, como KeyError: 'cofee', que dice qué salió mal. El marco de encima da el archivo, el número de línea y la función donde ocurrió, con la propia línea y marcas bajo la parte que falló. Los marcos más arriba son las llamadas que llevaron hasta allí, la más antigua primero, que es lo que significa “most recent call last”. La línea que falló no siempre es la que hay que arreglar: sigue el valor incorrecto hacia arriba por los marcos hasta donde se originó, y sáltate los marcos de dentro de las bibliotecas hasta el último de tu propio código. Un informe de SyntaxError no tiene cadena de llamadas, porque el archivo nunca empezó a ejecutarse.

Dos preguntas más difíciles parten de esta lección: un error lanzado en lo más hondo de una biblioteca, y un mismo error que dos versiones de Python describen de forma distinta. Piensa tu primer paso antes de abrir cada una:

Para recordar

• Lee un traceback desde abajo: la excepción y su mensaje, después la línea que falló y después las llamadas de encima.
• El error suele estar más arriba que la línea que falla: sigue el valor incorrecto hasta donde se originó, y sáltate los marcos de dentro de las bibliotecas.
• Un SyntaxError significa que no se ejecutó nada; cuando la línea que se muestra parece correcta, busca antes un corchete o unas comillas sin cerrar.
• Python 3.14 sugiere palabras clave mal escritas y explica las claves no hashables; las sugerencias Did you mean …? para nombres y atributos son más antiguas.
• Desatáscate con la documentación y help(), un print() de los valores implicados y un ejemplo mínimo, y nunca pegues secretos en una pregunta.