A practical Python debugging method

Treat an error as evidence instead of a verdict. The objective is to identify the smallest incorrect assumption and test it.

1. Reproduce the problem

Run the smallest version of the code that still fails. A reproducible failure gives you something concrete to test.

2. Read the traceback

The final exception type and message usually describe the immediate failure. Then move upward to find the line in your code that led to it.

3. Inspect values and types

Many bugs come from assumptions about a value. Inspect its type, length and representative value. A value that looks numeric may actually be a string such as "42".

4. State expected behavior

Write one sentence such as “I expect rows to contain three records.” Compare that expectation with reality.

5. Make the smallest change

Prefer a narrow fix that addresses the demonstrated cause. Rerun the same test after the change.

Common categories

• Name errors: a name is unavailable in the current scope.
• Type errors: an operation is applied to an incompatible type.
• Index/key errors: code requests data that is not present.
• Logic errors: the program runs but produces the wrong result.
• Environment errors: dependencies, paths, credentials or versions differ.

Debugging checklist

1. What exactly failed?
2. What value did the failing line receive?
3. What did you expect?
4. Where was that value created or changed?
5. Can you reproduce it with a smaller example?
6. What single change tests your hypothesis?

When asking an AI assistant for debugging help, include the traceback, smallest relevant code block, expected behavior and actual behavior.