No Such Table: Fix Django OperationalError Fast

Your view, shell command, or test crashes with django.db.utils.OperationalError: no such table: myapp_order. The model exists. The migration might even exist. But the database your process is reading has no such table, and Django won't invent one at query time. This error is a schema-reality mismatch, and its causes split neatly into five buckets you'll learn to check in order.

The impact ranges from annoying to severe. Locally it's a 2-minute migrate. In CI it's a red suite blocking every merge. In production it's checkout 500s because the deploy ran code before schema, or tests passing against a stale kept database while fresh installs crash. One variant — queries evaluated at import time — breaks every fresh environment while working perfectly on the developer's seasoned laptop.

This guide covers all five: unapplied migrations, missing migration files, wrong-database settings, --keepdb test staleness, and import-time queries. You'll get the triage order that names the cause in two minutes, the exact commands for each fix, and deploy patterns that keep schema ahead of code forever.

Migrations Unapplied: Schema Ships Before Code

The most common cause is also the simplest: the migration exists but was never applied to the database being read. You added a model, a teammate's branch added a table, or a fresh environment was provisioned — and nobody ran migrate against this particular database. Django models describe desired schema; only the migrator creates it. Querying before that step raises OperationalError naming the absent table, which is the database telling the truth about its contents.

Confirm with showmigrations: applied migrations carry [X], pending ones [ ]. If your app's latest migration shows [ ], the fix is python manage.py migrate — nothing more exotic. Verify afterward at the database level (dbshell plus .tables on SQLite, or the information-schema query on Postgres) rather than trusting the command's summary line. The table must exist where the app reads, not just where you assume it does.

The production lesson is ordering: migrate before traffic, every deploy, as a blocking step. Release-phase hooks, init containers, and entrypoint scripts all exist for this; pick the one your platform supports and make failed migrates block rollout. Code that queries a table must never reach a dyno whose database lacks it — the 47-minute outage in this article's incident came from deploying code beside schema instead of after it.

import sqlite3

# No-such-table reproduced with stdlib sqlite3 (same OperationalError).
con = sqlite3.connect(":memory:")
try:
    con.execute("SELECT * FROM shop_order")
except sqlite3.OperationalError as exc:
    print("reproduced:", exc)

# The migrate equivalent: create the table, then query.
con.execute("CREATE TABLE shop_order (id INTEGER PRIMARY KEY, total REAL)")
con.execute("INSERT INTO shop_order VALUES (1, 59.99)")
print("after migrate:", con.execute("SELECT * FROM shop_order").fetchall())

# Triage mapping:
#   showmigrations -> which migrations carry [X]
#   migrate        -> CREATE TABLE equivalents applied in order
#   dbshell .tables -> verify the table now exists

Missing Migration File: The Invisible Model

A model without a migration file is invisible to the migrator. migrate can run a hundred times and create nothing, because it only executes operations recorded in files under myapp/migrations/. This happens when a developer adds a model and forgets makemigrations, when the file is generated but never committed, or when a squash-and-rebuild cycle drops an operation. The symptom is distinctive: migrate reports nothing to apply, yet the table is missing.

Diagnose with the check command: makemigrations --check --dry-run exits nonzero when model state diverges from migration files, printing what it would generate. If it proposes a CreateModel for your missing table, you've found the gap. Generate the file with makemigrations myapp, read the operations (auto-detection occasionally misreads renames as drop-plus-create — fix those by hand), commit the file alongside the model change, then migrate.

Gate this in CI so it can't recur: the check command fails the build when files and models diverge, forcing the file into the same pull request as the model. Migration files are code — they get reviewed, tested, and deployed like code. Teams that enforce the same-commit rule stop seeing phantom-table failures because the schema change and its construction script can never separate.

import os

# Migration-file presence check (run from the repo root).
app = "myapp"
mig_dir = os.path.join(app, "migrations")
print("check these in YOUR repo:")
print(f"  ls {mig_dir}/            # expect 0001_initial.py, 0002_..., ...")
print("  python manage.py makemigrations --check --dry-run")
print("  # exit 0 = files match models; exit 1 = a file is missing")
print("  git log --oneline -5 --", mig_dir + "/")
print("  # to inspect tables: python manage.py dbshell, then .tables (SQLite) or \\dt (Postgres)")
print("  # or: python manage.py inspectdb | grep -i <table>")
print("rule: every model change ships its migration file in the same commit")

Wrong DB in Settings: The Table Exists Elsewhere

Sometimes the table exists — just not in the database your process reads. Development points at db.sqlite3 while a second settings file points at prod.sqlite3; staging uses Postgres while a debug override uses SQLite; two dynos mount different volumes. You migrate database A with full success, the app reads database B with full confidence, and the error persists through every retry because both sides are behaving correctly against different files.

The tell is identity: print DATABASES['default'] from the exact settings module the failing process loads, then compare NAME (or HOST/PORT for server databases) against where you ran migrate. SQLite makes this concrete — list *.sqlite3 files with sizes and timestamps; a 0-byte file created 5 minutes ago next to a 40MB file from last month means the app is reading a fresh empty database while you migrated the old one.

Standardize ruthlessly. One canonical DATABASES per environment, committed or templated, with the database NAME echoed into deploy logs at boot. Run migrate against that same NAME in the same job that deploys code. When the logs name the file or host on every boot, wrong-database mysteries collapse to a one-line diff instead of a two-hour hunt across volumes and settings files.

import os

# Which database would Django read? Print DATABASES identity.
print("candidate sqlite files in cwd:")
for f in sorted(os.listdir(".")):
    if f.endswith(".sqlite3"):
        print(f"  {f}  ({os.path.getsize(f)} bytes)")
print("then compare with settings:")
print("  grep -n -A 8 'DATABASES' mysite/settings*.py")
print("  # NAME must match the file you migrated")
print("rule: migrate the NAME the app reads, not the one you assume")

--keepdb Tests: Stale Schema, Green Runserver

Django's test runner builds a fresh database by applying every migration, then destroys it — unless --keepdb tells it to reuse last run's database. Reuse is fast and usually fine, until the migration set changes: new tables from new migrations don't exist in the kept schema, and tests fail with no-such-table while runserver (against your dev database) works perfectly. The failure looks like broken tests but is really a stale cache.

Confirm by forcing one clean rebuild: run the suite once without --keepdb (or delete the test_ database) and watch the failures vanish. The fix for local work is periodic recreation; the policy for CI is never passing --keepdb at all, so the pipeline always validates the full migration chain from zero. Fast suites that skip schema creation prove nothing about fresh installs — the exact environments new customers and new teammates hit.

Keep migrations quick so full rebuilds stay painless: squash long chains, avoid data migrations that loop millions of rows in tests (gate them behind settings flags), and keep test settings on SQLite or a disposable Postgres schema. When creating from scratch takes seconds, nobody reaches for --keepdb as a crutch, and the staleness class disappears with it.

Querying at Import Time: SQL Before Schema Exists

The sneakiest variant works on every seasoned machine and fails on every fresh one. A QuerySet evaluated at import time — a module-level FEATURED = Product.objects.filter(...), a class attribute, a decorator argument, a default parameter — executes its SQL during app loading, before any migrate could create the table. The developer's laptop has the table from months ago, so imports succeed; a new container, a rebuilt database, or a test runner hits no-such-table during check or collection, long before any test runs.

Find these with a targeted grep: QuerySet calls (objects.all/filter/get) at module or class scope, outside any function body. The fix is laziness — move the query into a method, a property, or get_queryset() so it executes per request against a ready database. Startup data needs belong behind AppConfig.ready() with a connection guard, or behind post_migrate signals that run after schema exists by definition.

Prove the fix on an empty database: build fresh (migrate --run-syncdb on a blank file), then run check and collect tests with zero queries at import. If collection passes against nothing, the import-time dependency is gone. This is the one no-such-table variant that code review must catch, because no amount of migrating fixes a query that runs before migrations exist.

import sqlite3

# Post-fix verification: assert the table exists before traffic.
con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE shop_coupon (id INTEGER PRIMARY KEY, code TEXT)")

tables = {r[0] for r in con.execute(
    "SELECT name FROM sqlite_master WHERE type='table'")}
required = {"shop_coupon"}
missing = required - tables
print("tables:", sorted(tables))
print("missing:", sorted(missing) or "none - traffic may proceed")
assert not missing, f"block deploy