Skip to content
Tutorials Center
My learning

Topics

Lesson 61 of 77 ยท Testing

Debugging Django Applications

Find and fix Django bugs faster: read tracebacks, decode common errors (no such table, NoReverseMatch, TemplateDoesNotExist), use the debug 404 page, Debug Toolbar, the shell, breakpoint() and SQL logging.

Tests tell you that something is broken. Debugging is how you find out why. Django makes this easier than most frameworks, because in development it shows you detailed error pages, and because a handful of exceptions cover most of the mistakes beginners (and veterans) make. This lesson gives you a routine: read the error, reproduce it in a shell, look inside the running code, and check what the database was asked.

It builds on Testing Django Apps and the request and response cycle, and the example outputs are real errors raised by Django in your browser.

Step 1: read the traceback from the bottom

A Python traceback lists the call chain from the first function to the one that failed. The useful information is at the bottom: the exception type and message. Above it, read upwards until you find the first line that points into your code (a file in your project, not in site-packages/django/...). That line is where your code called Django in a way Django did not accept.

With DEBUG = True, the browser shows an interactive version of this: each frame can be expanded, the local variables of each frame are listed, and the request details (headers, GET/POST data, session, settings) appear below. Those variable values are often the whole answer, for example "the pk is None, so of course the lookup failed."

The debug page exposes settings, paths and variables. Never run production with DEBUG = True. Production should log errors and show a plain 500 page (see Error Pages and Exceptions and Deploying Django).

The errors you will meet most

The table maps messages to usual causes. The example after it triggers each one on purpose, so you recognize them on sight.

Message (start) Usual cause Fix
OperationalError: no such table: app_model A migration was created but not applied, or never created makemigrations, then migrate (see Migrations)
no such column / column ... does not exist A field was added to the model, but the database still has the old shape Create and apply a migration
NoReverseMatch {% url %} or reverse() got a wrong name, wrong arguments, or a missing namespace Compare against your URL pattern (see URL Routing)
TemplateDoesNotExist Wrong template path, the app is not in INSTALLED_APPS, or DIRS/APP_DIRS is not set Check the template's location; the error lists every place Django looked
TemplateSyntaxError Unclosed tag, misspelled tag, missing {% load %} The message shows the tag and line
Page not found (404) in debug The URL does not match any pattern The debug page lists every pattern that was tried
MultipleObjectsReturned / DoesNotExist get() with a non-unique or wrong condition Use filter().first(), or fix the data/condition
RelatedObjectDoesNotExist Reading a one-to-one or foreign key that has no row Test with hasattr or use select_related and a default
FieldError: Cannot resolve keyword A misspelled field or lookup in filter() The message lists valid choices
CSRF verification failed A POST form without {% csrf_token %}, or a cross-site request See Security in Django
DisallowedHost The domain is missing from ALLOWED_HOSTS Add it to ALLOWED_HOSTS
ImproperlyConfigured A missing or wrong setting Read the message; it names the setting
Python Ten common Django errors, on purpose

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Look at number 5 and 6: NoReverseMatch says what it was given and what it expected, so compare that message with your path() definition and your {% url %} tag character by character. Number 7 shows only the first line; with DEBUG on, the real error page lists every directory and app Django searched, which is the fastest way to see that a template lives in the wrong folder. The last block shows why DEBUG is invaluable in development: the 404 page names the patterns that were tried, so a typo (post/ instead of posts/) becomes obvious.

Step 2: reproduce it in the shell

Before changing code, try to reproduce the problem in isolation:

Terminal
# read-only
python manage.py shell
Python
# read-only: inside the shell
from blog.models import Post
Post.objects.filter(published=True).count()
print(Post.objects.filter(title__icontains="django").query)   # the SQL Django will run

The shell loads your settings, so you can call your own code with real data. Printing a queryset's .query shows the SQL it will send; .explain() asks the database for its plan. Packages such as django-extensions add shell_plus, which auto-imports all your models. The test client is also a debugging tool: Client().get("/url/") lets you inspect response.status_code, response.context and response.content for one request without a browser.

Step 3: look inside with breakpoint()

When you cannot see why a value is wrong, stop the program and look. Insert breakpoint() where you want to pause and run the development server (python manage.py runserver, not under a process manager that hides the terminal):

Python
# read-only
def checkout(request):
    cart = get_cart(request)
    breakpoint()          # the terminal running runserver now shows a (Pdb) prompt
    total = sum(item.price for item in cart)
    return render(request, "checkout.html", {"total": total})

When the request reaches that line, the server's terminal shows the debugger prompt (Pdb):

Command Action
p expression or pp expression Print a value (or pretty-print)
n Run the next line
s Step into the function on this line
c Continue until the next breakpoint
l List source around the current line
w Show the call stack ("where")
u / d Move up or down the stack
q Quit the program

Remember to remove breakpoint() before committing. IDEs such as VS Code and PyCharm offer the same thing with clickable breakpoints. Setting the environment variable PYTHONBREAKPOINT=0 disables every breakpoint() call, which is a good safety net on servers.

Step 4: check what the database was asked

Slow pages and "why is this loading 400 times?" problems are usually query problems. Three tools help.

Django Debug Toolbar is a third-party panel that shows, for each page, the SQL queries (with duplicates highlighted), the templates rendered, the settings and the request details, right in the browser:

Python
# settings.py (read-only; pip install django-debug-toolbar)
INSTALLED_APPS += ["debug_toolbar"]
MIDDLEWARE.insert(0, "debug_toolbar.middleware.DebugToolbarMiddleware")
INTERNAL_IPS = ["127.0.0.1"]          # the toolbar only appears for these addresses

# urls.py
urlpatterns += [path("__debug__/", include("debug_toolbar.urls"))]

The toolbar only works in development (DEBUG = True plus INTERNAL_IPS) and needs an HTML response with a <body> tag. The panels are plain Python objects, so the next example reads the SQL panel's recorded data directly, the same data the browser panel draws. Alongside it, CaptureQueriesContext does the same job in tests, and the django.db.backends logger prints every query when DEBUG is on.

Python See every SQL query: the Debug Toolbar, CaptureQueriesContext and logging

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The toolbar shows what the template cannot: one query for the posts plus one query per post for its author, an N+1 problem. The toolbar highlights such repeated queries in red in the browser. Adding select_related("author") (see ORM Performance) joins them into a single query, which the logger confirms at the end.

A debugging routine

When something fails, work through this list:

  1. Read the message at the bottom of the traceback. Search for the exact exception text only after you have read it.
  2. Find the first frame in your code and check the local variables on the debug page.
  3. Reproduce in manage.py shell or with the test client, with the smallest input that fails.
  4. Pause with breakpoint() or print the suspicious values with the logging module (not left-over print calls).
  5. Check the SQL with the toolbar or connection.queries whenever data is missing, duplicated or slow.
  6. Write a test that fails because of the bug, fix it, and keep the test. See Testing Patterns.
  7. If a change broke something that worked, git diff or git bisect finds the commit.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A page raises 'OperationalError: no such table: blog_post'. What is the most likely cause?

    The code expects a table the database does not have. Run makemigrations if needed, then migrate.
  2. 2. Where in a traceback do you normally find the actual error?

    The traceback ends with the exception that was raised. Reading upwards to the first frame in your project shows the call that went wrong.
  3. 3. What does breakpoint() do when the development server reaches it?

    breakpoint() starts the Python debugger so you can print values and step through the code.
  4. 4. What does the SQL panel of Django Debug Toolbar help you find?

    It lists every query a request ran, highlights duplicates and shows timing, which makes N+1 patterns obvious.

Summary

  • Read tracebacks from the bottom, then find the first frame in your own code; the debug page shows local variables and the request.
  • A few exceptions cover most mistakes: missing table or column (migrations), NoReverseMatch, TemplateDoesNotExist, MultipleObjectsReturned/DoesNotExist and bad lookups.
  • Reproduce in manage.py shell or with the test client, pause with breakpoint(), and check SQL with the Debug Toolbar, CaptureQueriesContext or the django.db.backends logger.
  • Never leave DEBUG = True or stray breakpoint() calls in production, and turn each fixed bug into a test.

Next: Deploying Django.