How to Debug Common Python Errors

Understanding Tracebacks

A traceback is the general name for the message that’s printed on the screen when you encounter an error. Depending on the error and its source, the traceback may be just a few lines or stretch across many lines.

In the example below, you want to add two numbers but have forgotten to convert both to integers, so there’s an attempt to add a string and an integer:

>>> total = 23 + "3"
Traceback (most recent call last):
  File "python-input-0", line 1, in <module>
    total = 23 + "3"
            ~~~^~~~~
TypeError: unsupported operand type(s) for +: 'int' and 'str'

Looking at the traceback above, you can see your code printed to the screen, with the caret symbol (^) placed under the addition operator. This symbol highlights the position where the interpreter detects the problem.

When running the code, the interpreter encounters the addition operator between an integer and a string. These types can’t be added together in Python, so the interpreter raises a TypeError.

Debugging With Tracebacks

To debug using a traceback, it’s important to carefully read each line of the error traceback log to understand and locate the source of the problem. In the traceback above, Python points to line 1 as the source of the error.

In the codebase of the file, scroll to the line that’s been pinpointed and check it against the follow-up message in the traceback to better understand what went wrong.

You can go ahead and resolve the error by converting the string to an integer, or in this case, by changing the string "3" to the integer 3:

>>> total = 23 + 3
>>> total
26

In this corrected version, changing the type of "3" from a string to an integer resolves the error. If the string is stored in a variable, then you can use int() to convert it to an integer.

It’s important to note that sometimes, depending on the cause of the bug, the error output may be a syntax error that doesn’t include the typical Traceback keyword. For example, the code below attempts to add two integers but omits the addition operator, resulting in a SyntaxError:

>>> total = 23 3
  File "<python-input-0>", line 1
    total = 23 3
               ^
SyntaxError: invalid syntax

Notice that the error log is similar to the traceback but varies slightly in structure. The same step-by-step approach you used to decode tracebacks also works when dealing with syntax errors.

Understanding Debugging With print()

While you’re probably already familiar with Python’s built-in print() function, it’s worth taking a closer look at how you can use it strategically to debug your code.

The print() function is a built-in function that takes integers, strings, tuples, lists, and other objects, and prints them to the standard output—usually the terminal where you run your project.

In most cases, you use it to print output to the terminal when you’re unsure of the value a particular variable holds. In this way, you’re able to verify that the state of your code is exactly what you want at that moment. You can use the same technique when debugging.

Debugging With print()

In the following example, you have a function that checks for palindromes—words that read the same forward and backward:

>>> def find_palindromes(text):
...     words = text.split()
...     return [word for word in words if word == word[::-1]]
...
>>> find_palindromes("Dad plays many solos at noon, and sees a racecar.")
['solos', 'sees', 'a']

The function doesn’t find all the palindromes it’s supposed to return. In this case, it misses Dad, noon, and racecar. There are a couple of reasons for this. Dad is missed because of capitalization, while noon and racecar are missed because of punctuation. Here’s how you can debug the function using print():

• Print words, the list of words obtained after splitting the text, to check if punctuation or case sensitivity is an issue. This will reveal that punctuation remains attached to some words, so they need to be cleaned.

• Print all words after they’ve been cleaned—that is, after converting them to lowercase and removing non-alphanumeric characters.

• Print the list of words being checked for palindromes to confirm whether any matches are missing.

Here’s the updated code with print() calls added:

>>> def find_palindromes(text):
...     words = text.split()
...     print(f"{words = }")
...     # Remove punctuation and convert to lowercase
...     normalized_words = [
...         "".join(filter(str.isalnum, word)).lower()
...         for word in words
...     ]
...     print(f"{normalized_words = }")
...     palindromes = [
...         word for word in normalized_words if word == word[::-1]
...     ]
...     print(f"{palindromes = }")
...     return palindromes
...
>>> find_palindromes("Dad plays many solos at noon, and sees a racecar.")
words = ['Dad', 'plays', 'many', 'solos', (...), 'sees', 'a', 'racecar.']
normalized_words = ['dad', 'plays', 'many', (...), 'sees', 'a', 'racecar']
palindromes = ['dad', 'solos', 'noon', 'sees', 'a', 'racecar']
['dad', 'solos', 'noon', 'sees', 'a', 'racecar']

In this example, the calls to print() in the highlighted lines reveal the values of the list at each step of the palindrome check. Notice how you take advantage of the self-documenting feature of f-strings to display the corresponding variable names. For better formatting, especially when dealing with lists that span multiple lines, you could swap out print() for pprint() to display the data in a more readable way.

Adding the filter() for alphanumeric characters ensures that each word is stripped of non-alphanumeric attributes. Also, including .lower() converts all the strings to lowercase for consistent comparisons.

Don’t forget to remove the print() calls after you’ve resolved the errors, although you can always keep them in for logging or future debugging.

Understanding Breakpoints

A breakpoint is a marker or command in the code that signals the debugger to pause the program’s execution at a specific line. This allows you to inspect the program’s state and behavior at that moment.

By default, the interpreter executes code from top to bottom until it reaches the end of the file, encounters an error, or hits a breakpoint. When the program pauses at a breakpoint, you can execute a small part of the code and extend the sections bit by bit until you find the cause of the error.

In most code editors that support debugging, such as Visual Studio Code (VS Code) and PyCharm, breakpoints appear as visual markers, typically shown as small red dots next to the line numbers. You can add or remove breakpoints simply by clicking in the left margin beside the line of code you want to inspect.

Debugging With Breakpoints

When a program encounters a breakpoint, the debugger takes control of the program’s execution and pauses it at the specified line.

The debugger provides tools and a user interface that let you interact with the paused program. You can inspect variables, step through the code line by line, and better understand what your program is doing.

In this example, you’ll use VS Code to debug a function that capitalizes a list of fruits. It’s important to make sure you’re using a code editor that supports breakpoints.

First, define a function. In your code editor, create a file called fruit.py, and add the following function definition:

def capitalize_fruit_names(fruits):
    capitalized_fruit_names = []
    for fruit in fruits:
        capitalized_fruit_names.append(fruit.capitalize())
    return capitalized_fruit_names
capitalize_fruit_names(["apple", "BANANA", 98, "Mango"])

Next, you’ll set a breakpoint. Locate the line inside your function where you want to inspect the execution—in this case, inside the for loop. In your editor, click on the left margin next to the line number to set a breakpoint. A red dot will appear:

Notice the red dot next to line five above. Now you’re ready to start debugging. In VS Code, click the Run and Debug icon in the Activity Bar on the side of the window. When you do this, the debugging panel will appear and look similar to the following screenshot:

Use the arrow icons to step through your code line by line or to run the code until the next breakpoint without stepping into function calls. You can also click the triangular Play button to run the program without interruption.

If an error occurs, an exception popup will appear just below the faulty line in the code editor, highlighting where there’s an issue. Repeat the process, fix the code, and resume execution until you’re satisfied that the variables behave the way they should.

When using the breakpoint tool, you’ll notice that you get an error when an integer tries to complete the for loop process. This should guide you to put a check in place to exclude non-string values from the list.

Modify the capitalize_fruit_names() function so that it handles non-string inputs by replacing them with empty strings:

def capitalize_fruit_names(fruits):
    capitalized_fruit_names = []
    cleaned = [fruit if isinstance(fruit, str) else "" for fruit in fruits]

    for fruit in cleaned:
        capitalized_fruit_names.append(fruit.capitalize())
    return capitalized_fruit_names

The capitalize_fruit_names() function has been rewritten to check if fruit is of type string, and if it isn’t, the non-string value is replaced with an empty string (""). Now, run the debugger again with the breakpoints and observe the difference. The program no longer throws an error, and the variables fruit and capitalized_fruit_names behave as expected.

Using Python’s Built-in breakpoint() Function

Python’s built-in breakpoint() function is a convenient way to introduce debugging into your code. It was introduced in Python 3.7 and serves as an easy-to-use function. When Python encounters breakpoint() in your code, it pauses execution and enters an interactive debugging environment.

By default, breakpoint() uses Python’s built-in debugger, pdb, but you can configure it to use other tools. To use breakpoint(), simply add the function call to a new line in the code where you’d like to add the breakpoint. This will have a similar effect to clicking on the left margin in VS Code.

Understanding Debugging With Tests

Using testing for debugging means writing and running small, focused pieces of code that check whether your functions behave as expected. These tests act as automated checks that can alert you when something isn’t working right.

Tests don’t just help you find errors—they can also help prevent them. If you write your tests before your functions, they can guide how you write the code itself. This method of writing tests before the code that implements the tested functions is called Test Driven Development. Even without adopting full TDD, you can use tests to systematically reproduce bugs, which makes finding and fixing problems much easier.

Debugging With Tests

To see how you can debug with unit tests, create a file called test_fruit.py. In the file, add some test cases for the function called capitalize_fruit_names(). This takes in a list of fruit names and returns the list with the fruit names capitalized.

To handle cases where the function encounters a non-string element in the input list of fruits, you should skip the non-string input and only capitalize the strings. Here are the example tests:

import unittest
from fruit import capitalize_fruit_names
class TestFruit(unittest.TestCase):
    def test_empty_list(self):
        """with empty list"""
        self.assertEqual(capitalize_fruit_names([]), [])
    def test_lowercase(self):
        """with lowercase strings"""
        self.assertEqual(
            capitalize_fruit_names(["apple", "banana", "cherry"]),
            ["Apple", "Banana", "Cherry"],
        )
    def test_uppercase(self):
        """with uppercase strings"""
        self.assertEqual(
            capitalize_fruit_names(["APPLE", "BANANA", "CHERRY"]),
            ["Apple", "Banana", "Cherry"],
        )
    def test_mixed_case(self):
        """with mixed case strings"""
        self.assertEqual(
            capitalize_fruit_names(["mAnGo", "grApE"]),
            ["Mango", "Grape"],
        )
    def test_non_string_element(self):
        """with a mix of integer and string elements"""
        self.assertEqual(
            capitalize_fruit_names([123, "banana"]),
            ["", "Banana"],
        )
if __name__ == "__main__":
    unittest.main()

Here, you created five test cases based on the values of the list sent into the capitalize_fruit_names() function. Each test checks whether the function produces the expected output. When you run the tests, any failing case helps you identify what’s missing or incorrect in the function’s behavior.

As an experiment, revert the fruit.py file back to the original function, without any checks or validation for non-string values:

def capitalize_fruit_names(fruits):
    capitalized_fruit_names = []
    for fruit in fruits:
        capitalized_fruit_names.append(fruit.capitalize())
    return capitalized_fruit_names

When you run the test file, you’ll notice that all but the test_non_string_element test case passes. Here’s the error you’ll see for the failed test:

$ python -m unittest test_fruit.py
...E.
======================================================================
ERROR: test_non_string_element (test_fruit.TestFruit.test_non_string_element)
with a mix of integer and string elements
----------------------------------------------------------------------
Traceback (most recent call last):
  File "test_fruit.py", line 33, in test_non_string_element
    capitalize_fruit_names([123, "banana"]),
    ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^
  File "fruit.py", line 5, in capitalize_fruit_names
    capitalized_fruit_names.append(fruit.capitalize())
                                   ^^^^^^^^^^^^^^^^
AttributeError: 'int' object has no attribute 'capitalize'
----------------------------------------------------------------------
Ran 5 tests in 0.002s
FAILED (errors=1)

The error above is triggered by the test_non_string_element() test. In the test, you expect the function to replace any non-string values in the fruits list with empty strings.

However, this hasn’t been handled yet within capitalize_fruit_names(). Since you need the function to handle this replacement, add the following code to update the function so that non-string values are replaced with empty strings:

def capitalize_fruit_names(fruits):
    capitalized_fruit_names = []
    cleaned = [fruit if isinstance(fruit, str) else "" for fruit in fruits]

    for fruit in cleaned:
        capitalized_fruit_names.append(fruit.capitalize())
    return capitalized_fruit_names

If you run the tests again, you should get the following result, with all tests running smoothly:

$ python -m unittest test.py
.....
----------------------------------------------------------------------
Ran 5 tests in 0.000s
OK

By adding the replacement condition to the fruit.py file, the test case for non-string values is now handled, and all tests pass. This confirms that the capitalize_fruit_names() function behaves as it should.