Why does my AI coding agent hallucinate columns and tables that do not exist?
Quick answer: Because it has never queried your database. An AI coding agent reads your repository, so it infers a plausible schema from your code, your naming conventions, and patterns in its training data, then writes SQL against that guess. The result is idiomatic, review-passing SQL that fails at runtime with
column does not exist. The fix is to let the agent read the live catalog.
What is actually happening?
Section titled “What is actually happening?”An AI coding agent completes patterns based on everything it can see. It can see your source code, but not your database.
So when you ask for “a query that lists inactive users with their last order date,” the model assembles a schema from three sources:
- Your code. ORM models, migration files, type definitions, existing queries, GraphQL schemas. Real signal, but it is the schema your code thinks exists.
- Naming conventions. If your tables are snake_case and plural, it will
generate snake_case plural names. If it sees
user_idin one place, it will assumeuser_ideverywhere. - Training data. It has read many applications. Most of them have
created_at,updated_at,deleted_at,is_active,email, andstatus. These are strong prior probabilities.
None of those sources is information_schema. The model has never run a query
against your database. So when your table happens to use signup_ts instead of
created_at, or archived_at instead of deleted_at, or the soft-delete flag
lives on a join table rather than the main one, the agent generates the
statistically likely answer, and it is wrong.
The agent is interpolating rather than lying. Given everything it has seen,
created_at is a good bet, but a bet is not a fact.
Why is this failure mode so dangerous?
Section titled “Why is this failure mode so dangerous?”Most model errors announce themselves. This one does not.
The SQL looks right. It uses your table names, your casing, and your join style. It reads like something a competent engineer on your team wrote. There is nothing to catch in review unless the reviewer happens to have the actual column list memorised.
Type checking usually does not save you. Raw SQL strings are opaque to most
type systems. Even in ORMs, a hallucinated column often appears in a where
clause or a raw fragment that is not statically checked against the database.
It fails late. Postgres raises the error at execution, not at deploy. If the query is on a rare code path, such as an admin report, an error handler, or a monthly job, it can sit in the codebase for weeks and then fail in production, in the path you least wanted to be broken.
Trust breaks at the worst moment. A tool that is right 95% of the time and confidently wrong the other 5% requires verification on every result. That reduces much of the speed benefit you adopted it for.
The related and worse version is a hallucinated column in a WHERE clause that
happens to exist on the table but means something different from what the
agent assumed. That does not error at all. It quietly returns wrong results.
Why do not the usual workarounds hold up?
Section titled “Why do not the usual workarounds hold up?”Pasting DDL into the prompt
Section titled “Pasting DDL into the prompt”This works for that conversation. You paste CREATE TABLE statements for the
three tables involved and the agent produces correct SQL.
It fails on scope and repetition. You paste the tables you think are involved, so the agent still guesses at the fourth one it needed. You also have to do it again next session, and the session after, so the effort never builds up.
A schema dump in CLAUDE.md or .cursorrules
Section titled “A schema dump in CLAUDE.md or .cursorrules”This is the natural next step, and it causes the most damage.
The instinct is right: put real facts where the agent will always see them. The implementation has no refresh mechanism. You commit a schema dump on Tuesday, run four migrations over the next month, and the file becomes a detailed, authoritative-looking description of a database that no longer exists.
A stale schema file is often worse than no schema file. Without one, the agent guesses, and a guess carries some implicit uncertainty: the agent may hedge, ask, or write defensively. With a stale file, the agent has been handed something that presents as ground truth. It will not hedge; it will write SQL against your February schema with total confidence, and so will you when you review it.
If you keep a schema file anyway, make regenerating it part of your migration process: a script or CI step that rewrites it on every schema change. A file that is regenerated automatically is a cache. A file that is regenerated manually is a liability.
ORM model files as the source of truth
Section titled “ORM model files as the source of truth”These are better than a hand-written dump because they live next to the code and change with it. But ORM models describe what the application expects, not what is in the database. They drift in specific, common ways:
- A migration ran that the models were never updated for, or a model field was added in code before the migration shipped.
- Columns added directly in production during an incident.
- Views, materialized views, and columns created by extensions or other services that the ORM never modelled at all.
- Multiple services writing to the same database, each with its own partial model layer.
- Indexes and constraints, which most ORM model files describe incompletely, so the agent cannot tell whether the column it is filtering on is indexed.
The database is the only thing that knows what the database contains.
How do I let the agent read the real schema?
Section titled “How do I let the agent read the real schema?”Query the catalog. These queries are read-only and cheap. A connected agent can run them instead of inferring.
Columns and types for a table:
SELECT column_name, data_type, is_nullable, column_default, character_maximum_lengthFROM information_schema.columnsWHERE table_schema = 'public' AND table_name = 'orders'ORDER BY ordinal_position;One caveat matters because you are using a narrowly scoped role:
information_schema.columns only shows columns the current user has some
privilege on. A table the agent’s role was not granted SELECT on will not
error. It will simply be absent, and the agent will conclude it does not
exist. That is the same hallucination by missing fact this article is trying to
eliminate, now coming from an authoritative-looking source.
The fix is not to grant SELECT on everything. SELECT is a data privilege.
Granting it so the agent can discover a column name also hands it every row in
that table, which is a much larger concession than the problem requires. Read
pg_catalog.pg_attribute joined to pg_class instead. It is not
privilege-filtered, so the agent gets complete structural metadata, including
names, types, and nullability, without gaining access to any data. Keep an
explicit schema allowlist on those catalog queries, and widen SELECT only
where you intend the agent to read rows.
Every table and its column count, for orientation:
SELECT c.relname AS table_name, count(a.attname) AS columns, NULLIF(c.reltuples, -1)::bigint AS approx_rowsFROM pg_class cJOIN pg_namespace n ON n.oid = c.relnamespaceLEFT JOIN pg_attribute a ON a.attrelid = c.oid AND a.attnum > 0 AND NOT a.attisdroppedWHERE c.relkind IN ('r', 'p', 'm') AND n.nspname = 'public'GROUP BY c.relname, c.reltuplesORDER BY approx_rows DESC NULLS LAST;Primary keys, unique constraints, and foreign keys. ORM models describe these poorly, and the agent needs them to write a correct join:
SELECT con.conname AS constraint_name, con.contype AS type, -- p = primary, u = unique, f = foreign, c = check rel.relname AS table_name, pg_get_constraintdef(con.oid) AS definitionFROM pg_constraint conJOIN pg_class rel ON rel.oid = con.conrelidJOIN pg_namespace nsp ON nsp.oid = rel.relnamespaceWHERE nsp.nspname = 'public'ORDER BY rel.relname, con.contype;pg_get_constraintdef() gives you the full definition as text, including which
column references which table. This is the structure an agent needs to reason
over.
Indexes, so the agent knows what is cheap to filter on:
SELECT schemaname, tablename, indexname, indexdefFROM pg_indexesWHERE schemaname = 'public'ORDER BY tablename, indexname;Enum values, a quiet source of hallucinated string literals:
SELECT t.typname AS enum_type, e.enumlabel AS valueFROM pg_type tJOIN pg_enum e ON e.enumtypid = t.oidJOIN pg_namespace n ON n.oid = t.typnamespaceWHERE n.nspname = 'public'ORDER BY t.typname, e.enumsortorder;An agent that guesses status = 'canceled' when your enum says 'cancelled'
produces SQL that runs fine and returns zero rows forever.
How do I stop it coming back?
Section titled “How do I stop it coming back?”Make the live catalog the source of truth. Whatever the mechanism, such as a read-only MCP connection or a tool the agent can call, the schema the agent reasons over should be fetched when needed rather than copied from an earlier point in time.
If you keep a schema file, generate it. A CI step or migration hook that rewrites it on every schema change turns a liability into a cache. Fail the build if the committed file does not match a fresh dump.
Catch it in CI, not in production. Run the queries your code generates against a database restored from a real schema in tests. A hallucinated column fails immediately there.
Ask the agent to verify before it writes. If it has catalog access, “check the actual columns on that table before writing the query” is a cheap instruction that changes output quality because it converts a guess into a lookup.
Treat “the agent is confident” as no evidence at all. Confidence in a generated answer reflects how typical the answer is, not whether it is true of your database.
Why does my AI agent invent column names?
Because it has never seen your schema. It infers a plausible one from your code, your naming conventions, and patterns in its training data, then writes SQL against that inferred schema. A model that has read a million Rails apps will confidently produce created_at, user_id, and deleted_at whether or not your tables have them.
Why is a hallucinated column worse than an obvious mistake?
Because it is invisible until runtime. The SQL is syntactically valid and stylistically idiomatic, so it passes review, passes type checks in most stacks, and only fails when Postgres raises column does not exist, often in a code path that runs rarely or only in production.
Should I paste my schema into CLAUDE.md or .cursorrules?
Only if you have a mechanism to regenerate it. A committed schema dump has no expiry and stops matching reality after the next migration, which makes the agent confidently wrong instead of appropriately uncertain. A stale schema file is often worse than no schema file.
How do I let an AI agent read my real database schema?
Give it a read-only connection and let it query the catalog directly, information_schema.columns for columns and types, pg_indexes for indexes, and pg_constraint for keys and foreign keys. Then the schema it reasons over is the schema that exists right now, not a copy that drifted.
Are my ORM models not good enough?
They describe what the application expects, not what the database contains. They drift when migrations and models get out of sync, when columns are added directly in production, when other services write to the same database, or when views and extension-created objects were never modelled. They also describe indexes and constraints poorly.