Lesson 5 of 9
Module 3 · Coding with AI assistants
An error message tells you what went wrong and where. Read it yourself first; then, if you ask an assistant, give it exactly what it needs.
An error, on purpose
Real sequences often contain N, the standard letter for a base the sequencer could not call. The two lines below import the draft reverse_complement from Read before you run and give it a short sequence ending in N. Python stops and prints a traceback: a report of where the program was, step by step, when the error happened.
from ai_draft import reverse_complement
reverse_complement("ATGN")Reading the output
- Traceback (most recent call last): announces the report and tells you its order. Each function that was running when the error happened gets an entry, called a frame, starting with the outermost and ending with the one that failed. The most recent, and usually most useful, is therefore at the bottom.
- The … stands for earlier frames that have been left out here, including the line in your own cell that called the function. In this case they add nothing you do not already know.
- File "ai_draft.py", line 8, in reverse_complement says the program was inside
reverse_complement, at line 8 of ai_draft.py, and the next line repeats that line of code. - in <genexpr> refers to the generator expression on that same line, the part in brackets,
pairs[b] for b in seq, which produces one complement per base. Python counts it as a small function of its own, so it gets its own frame. - The row of ~ and ^ marks, which recent versions of Python add, point at the exact expression that failed:
pairs[b]. - KeyError: 'N' is the error type and its detail. A KeyError means a dictionary was asked for a key it does not contain; the key was 'N'.
A handful of error types cover most of what you will meet in this course, and the name alone points you towards the cause. A NameError means a name was used before it was defined, often a cell that was not run. A TypeError means a value of the wrong kind, such as adding a number to a string. A ValueError means the kind is right but the value is not acceptable, as in the empty-sequence check from Testing AI-written code. An IndexError is a list position that does not exist, a KeyError a dictionary key or table column that does not exist, an AttributeError a method or attribute the object does not have, and a FileNotFoundError a path that is wrong for this computer.
Tracebacks from libraries can be much longer. If pd.read_csv fails, the bottom frames may be deep inside pandas, in files you did not write. The error is rarely a bug in pandas. Read the last line for the error, then scroll up to the last frame that points to your own file or cell: that is the line you called the library from, and usually where the wrong file name, column or argument was given.
Remember also what a traceback cannot do. In Read before you run, three of the four bugs produced no error at all, only wrong numbers. A traceback appears only when Python cannot continue. For silent mistakes, your tests and hand-worked answers are the only alarm.
Worked example · reading a traceback from the bottom
line above:
pairs[b] in ai_draft.py, line 8 → the dictionary is pairscause:
pairs has A, T, G and C, but real sequences contain N for unknown basesStep by step. The last line names a KeyError with the key 'N', so some dictionary was missing the key 'N'. The frame above points to line 8 of ai_draft.py and marks pairs[b], so the dictionary is pairs and b was 'N' at that moment. Looking at how pairs is defined, it has exactly four keys: A, T, G and C. For the input "ATGN", the first three bases were looked up without trouble; the fourth was not there.
What the answer means. You found the cause from the traceback alone, in three steps, without asking anyone. That is worth doing every time, even if you then ask an assistant for help: you will write a better question, and you will be able to judge whether its answer addresses the real cause.
The fixed seqtools.py in Testing AI-written code adds "N": "N". Whether N should pass through, be removed or raise an error is a decision about your data, not a coding detail: make it yourself.
Go deeper: look inside the failed frame
A traceback tells you where the program stopped. A debugger, a tool that pauses a program so you can inspect it, lets you look at the values at that moment. In Jupyter or Colab, run %debug in a new cell straight after the error. You land inside the frame that failed, at a prompt marked ipdb>.
Type p b to print the variable b; here it shows 'N'. Type p pairs to see the dictionary and confirm the key is missing. u moves up one frame, towards your own code, and d moves back down. q quits. In a script, you can put breakpoint() on a line to pause there every time it runs. Checking a value yourself takes seconds, and it gives you a fact to put in your prompt instead of a guess.
A debugging prompt
When you do ask for help, the prompt below shows the shape of a good request. It is short, but nothing important is missing.
This Python 3.12 function raises KeyError: 'N' when the sequence contains N. Here is the function and the full traceback: [paste both] Expected: N should stay N in the reverse complement. Explain the cause in one sentence, then give the smallest change that fixes it.
What each line does
- The first line gives the Python version, the exact error and the input that triggers it. Version matters because error messages and library behaviour change between versions.
- The second line supplies the evidence: the function and the full traceback, pasted as text, not summarised.
- The third line states the behaviour you want. Without it, an assistant must guess whether N should be kept, dropped or rejected, and might choose differently from you.
- The last line asks for the cause first, in one sentence, and then the smallest change. A one-sentence cause is quick to check against your own reading of the traceback, and a small change is easy to review.
The answer still needs reading, with the same care as any other AI-written code. Check first that the cause it gives matches what you found from the traceback. Then look at the fix for a few patterns that make an error disappear without solving the problem.
- Silencing the error. Wrapping the line in
try:…except:so that nothing is reported. The program keeps running with a wrong or missing value. - Silently dropping data. Replacing
pairs[b]withpairs.get(b, "")stops the KeyError, becausegetreturns a default instead of failing. But every N becomes an empty string, so the result is shorter than the input and no longer lines up with it. Nothing warns you. - Changing the input. Removing every N from the sequence before the function runs. The error goes, and so do positions your later steps may rely on.
Each of these passes a quick look and fails the test you asked for: the reverse complement of "ATGN" should be "NCAT", four bases long. The fix you want here is the one in Testing AI-written code, adding "N": "N" to the dictionary, because it does exactly what the prompt's third line says and nothing else.
- Paste the full traceback and the code it points to, not a description of it.
- Make a minimal example: the shortest input that triggers the error. Often, making it reveals the bug.
- Ask for the smallest fix, and for the cause. A rewrite of everything hides what changed.
- After the fix, rerun your tests, and add a test for the case that failed.
Making a minimal example often solves the problem on its own. Suppose a script fails on a FASTA file of 20,000 sequences. If you cut the input down to the one sequence that fails, then to the shortest piece of it that still fails, you might end up with the four letters "ATGN", and at that point the cause is usually plain to see. If not, the minimal example is exactly what you paste into your question.
Rerunning the whole test suite matters because a fix in one place can break something elsewhere. Adding a test for the case that failed, for example one that checks the reverse complement of "ATGN" is "NCAT", means the same bug cannot quietly return later. A test written for a fixed bug is often called a regression test: a regression is when something that used to work stops working.
The ~ and ^ markers under the failing expression come from PEP 657, “Include fine grained error locations in tracebacks”, added in Python 3.11 (peps.python.org/pep-0657). A PEP (Python Enhancement Proposal) is the formal document in which a change to Python is proposed and recorded.
This matters when you share a traceback. A colleague on Python 3.10 or earlier will see no markers, and the markers can be switched off with the PYTHONNODEBUGRANGES environment variable or the -X no_debug_ranges option. So two tracebacks for the same bug can look different. Always state your Python version in a debugging prompt, as the lesson’s template does.
Key point
Every fixed bug should leave a test behind, so it can never come back unnoticed.
A second example. If a function that reads sample sheets once crashed on a file with a blank last line, the fix should come with a test that reads a small sheet ending in a blank line. Months later, when someone rewrites the reading code, that test will fail at once if the blank-line problem returns.
Further reading · Module 3Wilson et al. 2014: testing and review habits that apply to AI-written code too. · All reading for this course
Check your understanding
1. Where do you start reading a Python traceback?
2. What is a minimal example?
3. What should you do after a bug is fixed?
Up next
Lesson 6
Explaining, documenting and translating