Skip to content

Why does my AI coding agent hallucinate columns and tables that do not exist?

Last updated

View as Markdown

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.

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:

  1. Your code. ORM models, migration files, type definitions, existing queries, GraphQL schemas. Real signal, but it is the schema your code thinks exists.
  2. Naming conventions. If your tables are snake_case and plural, it will generate snake_case plural names. If it sees user_id in one place, it will assume user_id everywhere.
  3. Training data. It has read many applications. Most of them have created_at, updated_at, deleted_at, is_active, email, and status. 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.

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.

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.

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_length
FROM information_schema.columns
WHERE 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_rows
FROM pg_class c
JOIN pg_namespace n ON n.oid = c.relnamespace
LEFT JOIN pg_attribute a
ON a.attrelid = c.oid AND a.attnum > 0 AND NOT a.attisdropped
WHERE c.relkind IN ('r', 'p', 'm')
AND n.nspname = 'public'
GROUP BY c.relname, c.reltuples
ORDER 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 definition
FROM pg_constraint con
JOIN pg_class rel ON rel.oid = con.conrelid
JOIN pg_namespace nsp ON nsp.oid = rel.relnamespace
WHERE 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,
indexdef
FROM pg_indexes
WHERE schemaname = 'public'
ORDER BY tablename, indexname;

Enum values, a quiet source of hallucinated string literals:

SELECT
t.typname AS enum_type,
e.enumlabel AS value
FROM pg_type t
JOIN pg_enum e ON e.enumtypid = t.oid
JOIN pg_namespace n ON n.oid = t.typnamespace
WHERE 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.

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.