Common Beginner Errors, Explained

How to read a traceback, then every error a beginner meets in the first months, with the exact message (Python 3.12/3.13 wording; older versions are terser), what it really means, the usual causes in AI-flavoured code, and the fix. When tutoring, give the "means" line and a hint first; give the fix after the learner has looked.

#Contents

• Reading a traceback
• Quick lookup table
• SyntaxError
• IndentationError and TabError
• NameError
• TypeError
• ValueError
• KeyError
• IndexError
• AttributeError, especially on None
• ModuleNotFoundError and virtual environment problems
• ImportError and circular imports
• UnboundLocalError
• RecursionError
• ZeroDivisionError
• FileNotFoundError and paths
• JSONDecodeError
• Errors with no traceback: silent bugs
• Async errors
• Debugging routine to teach

#Reading a traceback

Traceback (most recent call last):
  File "/home/ada/bot/main.py", line 22, in <module>
    reply = ask(history)
            ^^^^^^^^^^^^
  File "/home/ada/bot/main.py", line 15, in ask
    return data["choices"][0]["message"]["content"]
           ~~~~^^^^^^^^^^^
KeyError: 'choices'

Teach this order:

1. Bottom line first: the error type (KeyError) and its message ('choices'): "the dict has no key choices".
2. The frame just above: file, line 15, function ask, and the code. The ~~~^^^ markers (3.11+) point at the exact sub-expression.
3. Walk up to see how execution got there: line 22 called ask.
4. Ask "what value did Python have?" Here: print(data) reveals {"error": {"message": "invalid api key"}}, so the real problem is authentication, not the indexing.
5. Frames in library code (site-packages/...) are rarely where the bug is; find the last frame in your own files.

"During handling of the above exception, another exception occurred" means a second error happened inside an except block. "The above exception was the direct cause of the following exception" comes from raise ... from e. Read both: the first is usually the root cause.

#Quick lookup table

#SyntaxError

Python parses the whole file before running it, so a SyntaxError means no line ran, not even the ones above it.

def greet(name)                 # SyntaxError: expected ':'
    print(f"Hi {name}")

AI-flavoured classic: pasting a JSON example into Python with true/false/null gives NameError (not SyntaxError) because Python spells them True/False/None. Use json.loads('...') on the JSON text instead.

#IndentationError and TabError

for chunk in chunks:
print(chunk)                      # IndentationError: expected an indented block after 'for' statement on line 1

def score(x):
    if x > 0:
        return 1
      return 0                    # IndentationError: unindent does not match any outer indentation level

Teach: indentation IS the block structure. An else must align with its if; an except with its try. A line that is outdented ends the block, so a mis-indented return inside a loop returns after the first item:

def total_tokens(chunks):
    total = 0
    for c in chunks:
        total += len(c.split())
        return total          # BUG: inside the loop, returns after the first chunk

#NameError

NameError: name 'respnse' is not defined. Did you mean: 'response'?

Causes:

• Typo (3.10+ suggests the right name).
• Used before assigned, e.g. a variable created only inside an if branch that didn't run, or in a cell you haven't run yet (Jupyter).
• Missing import: name 'json' is not defined -> import json.
• Forgot quotes: model = gpt instead of model = "gpt".
• JSON literals: true, false, null -> True, False, None.
• Using a function's local variable outside the function.

#TypeError

The most varied error; read the message carefully.

#ValueError

int("3.5")                      # ValueError: invalid literal for int() with base 10: '3.5'
a, b = [1, 2, 3]                # ValueError: too many values to unpack (expected 2)
a, b, c = "ab".split()          # ValueError: not enough values to unpack (expected 3, got 2)
["a", "b"].index("z")           # ValueError: 'z' is not in list
import math; math.sqrt(-1)      # ValueError: math domain error

Fixes: inspect the actual value with print(repr(x)) (it shows hidden spaces and newlines like '42\n'), validate before converting, use str.partition or split(maxsplit=1) when the number of parts varies.

#KeyError

config = {"model": "small", "temperature": 0.2}
config["max_tokens"]            # KeyError: 'max_tokens'

Causes and fixes:

• Key genuinely optional -> config.get("max_tokens", 256).
• Spelling or case ("Temperature"), trailing space in a key from a CSV header ("model ") -> print(list(config)).
• The API returned a different shape (an error object) -> print the whole response first.
• Counting -> counts[w] = counts.get(w, 0) + 1 or collections.Counter.
• Grouping -> collections.defaultdict(list).

#IndexError

results = []
best = results[0]               # IndexError: list index out of range

Causes: empty list (no search results, empty file); off-by-one (items[len(items)], range(len(items) + 1)); indexing the wrong level of a nested structure; deleting from a list while looping by index.

Fixes: check if results: before indexing; use items[-1] for the last item; iterate with for item in items instead of indexes; trace the loop to see the index on the failing step.

#AttributeError, especially on None

AttributeError: 'NoneType' object has no attribute 'strip'

It means a variable you expected to be a string/list/object is None. Ask "which function gave me None?":

Other AttributeErrors: 'list' object has no attribute 'split' (you have a list of strings, not a string: loop over it); 'str' object has no attribute 'append' (strings are immutable); module 'random' has no attribute 'choice' (your file is named random.py); 'dict' object has no attribute 'content' (use msg["content"], not msg.content, unless the SDK returns objects).

#ModuleNotFoundError and virtual environment problems

ModuleNotFoundError: No module named 'httpx'

"The package is not installed in the Python that is running this code." The classic story: pip install httpx succeeded, the error persists, because pip belongs to a different Python than python (system vs venv vs conda vs the editor's interpreter).

Diagnose:

python -c "import sys; print(sys.executable)"   # which Python runs your code
python -m pip -V                                 # which Python pip installs into
python -m pip list | grep -i httpx              # is it there?

Fix:

source .venv/bin/activate          # or .venv\Scripts\activate on Windows
python -m pip install httpx        # ALWAYS python -m pip, so pip matches python
# with uv: uv add httpx && uv run main.py

Other causes:

• Package name differs from import name: pip install scikit-learn -> import sklearn; pip install python-dotenv -> import dotenv; pip install beautifulsoup4 -> import bs4; pip install pillow -> import PIL; pip install pyyaml -> import yaml.
• Editor/Jupyter uses another interpreter: in VS Code "Python: Select Interpreter" -> .venv; in Jupyter %pip install httpx installs into the kernel's Python.
• Your own module: ModuleNotFoundError: No module named 'utils' when running from a different folder; run from the project root or use python -m package.module.
• externally-managed-environment error from pip (PEP 668, modern Linux/macOS Homebrew): create and activate a venv instead of installing globally.

#ImportError and circular imports

ImportError: cannot import name 'Client' from 'mylib' (/home/ada/bot/mylib.py)
ImportError: cannot import name 'build_prompt' from partially initialized module 'prompts' (most likely due to a circular import)

First: typo or version difference (the name moved in a newer release; check the installed version with python -m pip show mylib). Second: a file named like the library shadows it (mylib.py in your folder). Third: circular import: a.py imports b.py which imports a.py; move shared code into a third module or import inside the function.

#UnboundLocalError

total_tokens = 0

def add(n):
    total_tokens += n          # UnboundLocalError: cannot access local variable 'total_tokens'
                               # where it is not associated with a value

Because the function assigns to total_tokens, Python decides at compile time that it is local for the whole function; += reads it before any local value exists. Fix by passing and returning (def add(total, n): return total + n), using an object to hold state, or (last resort) global total_tokens. In nested functions use nonlocal.

#RecursionError

RecursionError: maximum recursion depth exceeded

A function keeps calling itself. Usual causes: missing base case, a base case that is never reached (n - 1 on floats, wrong comparison), or recursing on the same input. Accidental recursion also happens with properties and __getattr__ (return self.name inside the name property), and with __repr__ of objects that reference each other. Fix the base case or use a loop; Python's default limit (~1000) is deliberately low.

def flatten(items):
    out = []
    for x in items:
        if isinstance(x, list):
            out.extend(flatten(x))      # recursive case: smaller input
        else:
            out.append(x)               # base case: not a list
    return out

print(flatten([1, [2, [3, 4]], 5]))     # [1, 2, 3, 4, 5]

#ZeroDivisionError

ZeroDivisionError: division by zero. In AI code: average of an empty list of scores, accuracy with zero examples, cosine similarity with an all-zero vector (empty text embedding). Guard: return dot / norm if norm else 0.0, or if not scores: return None.

#FileNotFoundError and paths

FileNotFoundError: [Errno 2] No such file or directory: 'data/faq.json'

Relative paths are resolved from the current working directory (where you ran python), not from the script's folder. Fixes:

from pathlib import Path

HERE = Path(__file__).resolve().parent          # folder containing this script
faq_path = HERE / "data" / "faq.json"
print(faq_path, faq_path.exists())               # debug: print the absolute path

On Windows, write paths with forward slashes or raw strings (r"C:\new\data"), because "\n" in a normal string is a newline. Related: IsADirectoryError (you passed a folder), PermissionError (file open in another program or no rights), UnicodeDecodeError (pass encoding="utf-8").

#JSONDecodeError

json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)

"Expecting value at char 0" usually means the text is empty or is not JSON at all (an HTML error page, a model's prose). With model output also check: Markdown fences (```json), single quotes ({'a': 1} is a Python repr, not JSON), trailing commas, truncated output because max_tokens was too low. Print repr(raw) first; then strip fences, extract from the first { to the last }, and ask the model for JSON mode / structured output where available.

#Errors with no traceback: silent bugs

These do not crash, which makes them worse. Teach them by tracing.

#Async errors

#Debugging routine to teach

1. Read the last line of the traceback aloud in plain words.
2. Find the last frame in your own file; look at that exact line.
3. Ask "what were the values?" and print them with print(f"{x=}, {type(x)=}"), or run scripts/explain_concepts.py trace snippet.py on a small reproduction.
4. Make a 5-line reproduction: if it reproduces, you understand it; if not, the difference is the clue.
5. Change one thing, re-run, observe.
6. Afterwards, name the concept behind the bug (aliasing, scope, None from an in-place method) so it sticks.

Use breakpoint() (opens pdb: n next line, s step into, p x print, c continue, q quit) once the learner is comfortable with print debugging.