Practical Python

How to Read a Python Traceback

Read the final exception, identify the line in your code that matters, then check the smallest input that reproduces the bug.

Read the final line of the Python traceback first. It names the exception and usually describes the operation that failed. Then work back through the frames to find the line in your code that supplied the value or called the function. Run the smallest example that still produces the error before changing the code.

Tell a shell error from a Python traceback

A syntax error means Python could not parse the source as written. An import error concerns finding or loading a module. A file error concerns a path or file operation. A permission error concerns an operation the current account or policy did not allow.

The shell can also report errors before Python starts. If the command itself is unknown, the problem is different from an exception raised inside a running script. Check the interpreter and working folder early.

Reproduce the smallest failure

Keep the command, input, interpreter version, and exact error. Then reduce the input while preserving the problem. If one CSV row causes a conversion failure, investigate that row rather than changing the report layout.

Use synthetic data when asking for help. Remove secrets and personal information, but preserve the structure that causes the error. A completely different sample may remove the very condition someone needs to diagnose.

Inspect values at a boundary

Print or inspect a value immediately before the operation that fails. Check its type as well as its appearance. The string "12" and the number 12 can look similar in output but behave differently when used in calculations.

Keep debugging output separate from a machine-readable result. A JSON report becomes invalid if arbitrary diagnostic text is printed into the same output stream. A command-line tool can use standard error for diagnostics and a file for its structured result.

Handle the error you understand

Catch specific exceptions where you can make a sensible decision. A broad handler that prints “something went wrong” and returns success makes diagnosis harder. If the tool could not collect its input, a non-success exit status is useful to the person or scheduler running it.

Do not use elevated privileges as a universal repair. A protected directory may mean the output path is wrong. A TLS error may concern the clock or trust configuration; disabling verification changes the security of the connection rather than explaining the failure.

Turn the fix into a regression case

Once you understand the problem, create a small test that fails before the correction and passes afterward. Record the expected behavior in plain language. The goal is to preserve the lesson from the failure so the next edit does not recreate it.

Start from the traceback and narrow the evidence

Take an error such as ValueError: invalid literal for int() when converting a CSV value. The traceback identifies where the conversion happened. Look at the specific value. An empty field, a number containing a decimal point, and a field containing a column heading can all cause conversion failure, but each has a different fix.

Reduce the input to one row that works and one row that fails. Put both examples beside the code that decides how to handle them. If you support only whole numbers, reject the decimal with an explanation. If the field allows decimals, change the conversion and update the rule. Treat the failure as information about the contract you need to clarify.

When the program runs and gives the wrong answer

Begin with a tiny result you can compute manually. For a subtotal, choose two or three records with simple numbers. Print or inspect the records immediately before summing them. If an unexpected record appears there, trace the filter before changing the arithmetic.

Write down a competing explanation. A total might be high because the loop sees duplicate input or because a branch adds the wrong value. Check the list of accepted records first. You will learn which part of the program to examine and avoid introducing a second change in an area that already works.

Reproduce the failure before changing the code

Capture the input, command, expected behavior, and observed result. If your code requires a file supplied by another person, create a small replacement with the same problematic shape. This preserves the relevant conditions while making the example easy to share.

Run it from a fresh terminal. If the failure disappears, compare the environment rather than treating the issue as fixed. The interpreter, current directory, inherited settings, and prior output files can change what a program sees. Use the simplest environment in which the failure still happens.

Verify the repair against the original case

After the repair, rerun the smallest failing example and the ordinary case. A fix for blank rows can accidentally reject a legitimate zero. A fix for an output path can accidentally change where files are written when a user supplies an explicit destination. Check a nearby assumption whenever the repair changes a rule.

Keep the useful reproduction as a test or fixture. Give it a name that explains the behavior it protects. A future error message then gives you context about the original decision instead of leaving you to rediscover why the special case exists.

After you’ve worked out why the operation fails, learn when to catch a Python exception and when to let it reach the caller.

Sources and further reading

Related reading

Browse Practical Python · Explore project tutorials

Search PythonProjects.org