Reading error messages and tracebacks

What you'll learn

• Read a traceback from the bottom up and know which line to look at first
• Recognize the five errors beginners hit most and what each one is really saying
• Tell a syntax error, which stops the program before it starts, from a runtime error
• Use Python 3.14's improved messages, which often suggest the fix

Concept

An error message is not a failure; it is Python telling you precisely where its understanding of your program stopped matching yours. The block of text it prints is called a traceback, and it has a fixed shape. Read it from the bottom. The last line names the error and explains it. The lines above show where it happened, most recent call last, so the location right above the message is the one to look at first.

There are two kinds of error. A SyntaxError (and its cousin IndentationError) means Python could not even read the file, so nothing ran at all. It points at the place where reading broke down, which is sometimes a line after the real mistake, like a missing closing bracket. Every other error is a runtime error: the file was fine, the program ran, and a specific line asked for something impossible.

Five runtime errors account for most of what a beginner sees. Each has a precise meaning, and learning to translate the name into the question it is asking will save you hours. Python 3.14 helps more than any version before it: a NameError often ends with a "Did you mean" suggestion, an AttributeError names the method you probably wanted, and a SyntaxError for a missing colon or unmatched bracket says so directly. Read the whole last line, because the suggestion is frequently the fix.

Once you can read the message, fixing it becomes a routine rather than a scramble. Read the last line, find the line number right above it, and open that line. Then ask one question: is it a typo or a type mix-up? If yes, fix it and rerun. If no, print the variables right before that line to see what they actually hold, then fix and rerun. The same steps every time turn a red wall of text into a two-minute fix.

Code

A NameError with a suggestion. The name is misspelled on the print line, and Python guesses what was meant.

# name_error.py
message = "hello"
print(mesage)

Traceback (most recent call last):
  File "name_error.py", line 2, in <module>
    print(mesage)
          ^^^^^^
NameError: name 'mesage' is not defined. Did you mean: 'message'?

A TypeError from mixing text and a number. The message names both types, which tells you exactly which value to convert.

# type_error.py
age = 29
print("Age: " + age)

Traceback (most recent call last):
  File "type_error.py", line 2, in <module>
    print("Age: " + age)
          ~~~~~~~~^~~~~
TypeError: can only concatenate str (not "int") to str

A traceback with two levels. The error happens inside average, but the useful context is the call in the main program that passed an empty list; reading upward gives you both.

# two_levels.py
def average(values):
    return sum(values) / len(values)

scores = []
print(average(scores))

Traceback (most recent call last):
  File "two_levels.py", line 5, in <module>
    print(average(scores))
          ~~~~~~~^^^^^^^^
  File "two_levels.py", line 2, in average
    return sum(values) / len(values)
           ~~~~~~~~~~~~^~~~~~~~~~~~~
ZeroDivisionError: division by zero

A SyntaxError is reported before anything runs: the first print never happens. The message points straight at the missing colon.

# syntax_error.py
print("this never prints")
if True
    print("missing colon above")

  File "syntax_error.py", line 2
    if True
           ^
SyntaxError: expected ':'

Try it yourself

Create broken.py and deliberately produce each of the five runtime errors from the table, one at a time, reading each traceback before fixing it: use an undefined name, add a string to a number, call int("ten"), index past the end of a short list, and read a missing dictionary key. Then write down, in one sentence each, what the last line told you.

Common mistakes

• Reading the traceback from the top. The top is the outermost call; the useful line is at the bottom, right above the error message.
• Fixing the reported line when the cause is earlier. A SyntaxError for an unclosed bracket points at the next line; a NameError from a typo points at the use, not the definition.
• Treating the error as a verdict. It is a location and a reason. Read both, change one thing, run again.

What's next

• Read a traceback bottom-up: the last line says what, the line above says where, the rest says how you got there.
• NameError, TypeError, ValueError, IndexError, and KeyError each ask one precise question; learn the translation.
• Syntax errors stop the file before it runs; 3.14's messages often include the fix.

You can read every message the interpreter throws at you. Next you will put the whole Fundamentals level together in one program: a command-line quiz game.