Django Troubleshooting

Introduction

Django errors often look cryptic until you recognize the pattern—virtualenv not activated, missing migration, CSRF failure, or Nginx 502 while Gunicorn is down. This chapter maps common symptoms to fixes and links back to the chapters where each topic is taught in depth.

Prerequisites

• You have run at least one Django project locally — First Django Project
• Basic terminal and log reading

Diagnostic Flow

Error → classify (install / settings / DB / template / deploy) → read traceback → fix one layer

Installation and Import Errors

ModuleNotFoundError: No module named 'django'

Cause: Virtual environment not activated or Django not installed in current Python.

Fix:

source .venv/bin/activate
pip install -r requirements.txt
python -c "import django; print(django.get_version())"

See Environment and Installation.

ImproperlyConfigured: DJANGO_SETTINGS_MODULE

Cause: Wrong settings path in manage.py, wsgi.py, or shell.

Fix: Match config.settings.development (or your split module). Export explicitly:

export DJANGO_SETTINGS_MODULE=config.settings.development
python manage.py check

See Settings and Multi-Environment.

Database Errors

django.db.utils.OperationalError: no such table

Cause: Models defined but migrations not applied.

Fix:

python manage.py makemigrations
python manage.py migrate

See Models and Migrations.

MySQL access denied or unknown database

Cause: Wrong DATABASES credentials or database not created.

Fix: Create DB and user on MySQL; align utf8mb4 — MySQL configuration.

Migration conflicts (Conflicting migrations detected)

Fix:

python manage.py makemigrations --merge
python manage.py migrate

Coordinate with teammates—do not delete applied migrations on main.

Template and URL Errors

TemplateDoesNotExist

Cause: Wrong path, app not in INSTALLED_APPS, or missing APP_DIRS.

Fix: Use blog/post_list.html with app under blog/templates/blog/. See Templates.

NoReverseMatch

Cause: URL name typo, missing namespace, or wrong kwargs.

Fix: python manage.py show_urls (django-extensions) or grep name= in urls.py. See URLs and Routing.

CSRF and Auth

Forbidden (403) CSRF verification failed

Cause: Missing {% csrf_token %}, cookie blocked, or cross-origin POST without trusted origin.

Fix: Add token to forms; set CSRF_TRUSTED_ORIGINS for HTTPS subdomains. See Forms and CSRF.

Redirect loop on login

Cause: LOGIN_URL points to a view that also requires login.

Fix: Ensure login view is public; check @login_required on accounts/login/.

See Authentication.

Production and Deploy

DisallowedHost at /

Cause: Host header not in ALLOWED_HOSTS.

Fix: Add domain to ALLOWED_HOSTS in production settings.

Static files 404 in production

Cause: Forgot collectstatic or wrong Nginx alias.

Fix:

python manage.py collectstatic --noinput

Verify path matches Nginx — Static in Production.

502 Bad Gateway from Nginx

Cause: Gunicorn not running, wrong proxy_pass port, or firewall.

Fix:

sudo systemctl status hello_django
curl -I http://127.0.0.1:8000/

See Gunicorn deploy and Production project.

Changes not visible after deploy

Cause: Old Gunicorn workers, missed migrate, or browser cache.

Fix: Restart Gunicorn; run migrations; hard-refresh static with hashed filenames.

DRF and API

403 on POST with Token auth

Cause: Missing Authorization: Token <key> header or wrong authentication class order.

Fix: Obtain token via /api/auth/token/; send header on write requests. See DRF Basics.

CORS error in browser (SPA)

Cause: Frontend origin not allowed.

Fix: Install django-cors-headers and set CORS_ALLOWED_ORIGINS. See API Auth and CORS.

Quick Reference Table

FAQ

How to see SQL queries?

django.db.connection.queries with DEBUG=True, or django-debug-toolbar.

runserver works, Gunicorn 500?

Check DJANGO_SETTINGS_MODULE, static SECRET_KEY, and Gunicorn logs—production settings differ.

Admin login fails?

User needs is_staff=True — Django Admin.

Tests pass locally, fail in CI?

CI may use different settings or missing MySQL service—use SQLite for CI or provision DB in workflow — Docker and CI.

Where to ask for help?

Django forum, Stack Overflow with traceback + Django version—after reading Resources.