PGRST204 Column Not Found: When to Blame the Schema Cache

The first FAQ block this site’s pipeline ever tried to store died on arrival. August 13, a scheduled slot, first INSERT into a table named post_faqs:

POST /rest/v1/post_faqs
{"post_slug": "google-trends-rss-feed", "position": 1, ...}

HTTP 400
{"code":"PGRST204","details":null,"hint":null,
 "message":"Could not find the 'post_slug' column of 'post_faqs'
            in the schema cache"}

I read “schema cache” and went where the words pointed: staleness, reload commands, infrastructure. The actual bug was one word. The column is called post_id. I had written post_slug from memory, because almost everything else in the Supabase database that runs this site keys on slugs. Nothing was stale anywhere. The cache was accurately reporting that a column I invented does not exist.

The gap between where this error points and where the bug usually lives seemed worth mapping properly, because the schema cache is sometimes at fault, and the fixes for the two cases have nothing in common. So this morning I threw deliberately wrong requests at our production project and recorded what came back.

Two causes, opposite fixes

PGRST204 sits in group 2 of PostgREST’s error reference, which is literally titled “Schema Cache Errors,” and the docs say of that group: “Most of the time, these errors are solved by Schema Cache Reloading.” For some people that is exactly right. Supabase issue #42183 (January 2026) describes columns added with plain ALTER TABLE that stayed invisible to the API through NOTIFY pgrst reloads, permission re-grants, and a project pause/resume. Issue #39446 (October 2025) reports a freshly created table returning PGRST204 and PGRST205 for more than ten hours. Both are still open as I write this.

And yet my incident had the same error text with a cause from a different universe: a wrong name, typed by me, on the first attempt against a table that had existed for weeks. Reloading anything would have fixed nothing. The message cannot tell you which world you are in. The probes below can.

One missing column, three different errors

I took a column that has never existed, bogus_col, and referenced it from every position PostgREST offers. Same database, same table, same nonexistent name:

The split is clean. 42703 is a PostgreSQL SQLSTATE: those requests were compiled into SQL, sent to the database, and the database itself rejected the column. The PGRST2xx responses never reached the database. When you write, PostgREST has to build the INSERT statement out of your body keys, so it validates each key against its cached copy of the schema first, and a miss dies at that gate. That is the entire reason the message says “schema cache”: on the write path, the cache is the only thing that ever looked at your column name.

The one error that refuses to suggest a fix

The asymmetry gets sharper when the name is almost right. I asked for titl on a table whose real column is title:

# read path: PostgreSQL answers, and helps
?select=titl        → 42703  "column posts.titl does not exist"
                      hint: Perhaps you meant to reference
                            the column "posts.title".

# unknown table: PostgREST answers, and helps
GET /rest/v1/post   → PGRST205  hint: Perhaps you meant
                                  the table 'public.posts'

# write path: PostgREST answers, and does not
PATCH {"titl": …}   → PGRST204  hint: null

PostgreSQL ships a did-you-mean for columns. PostgREST itself ships one for tables on PGRST205. PGRST204 — the error you get for the most common mistake, one letter off in a write body — carries hint: null even when the correct answer is a single character away. Whatever the reason, the practical consequence is that the write path gives you the least help exactly where you need it most.

One thing PGRST204 does do reliably: it quotes your input back verbatim, inside single quotes. When I sent "post_id " with a trailing space, the message read Could not find the 'post_id ' column, space preserved between the quotes. Same for case: 'Post_Id' comes back exactly as typed. Read the quoted name character by character before you touch anything else; invisible whitespace and casing are two of the three usual suspects, and the quotes are where they become visible.

Stop guessing: dump the cache

The debate between “my spelling is wrong” and “the cache is stale” does not need to be a debate, because the cache will show you its contents. The root of every PostgREST deployment serves an OpenAPI description generated from the schema cache itself:

curl -s "$SUPABASE_URL/rest/v1/" -H "apikey: $ANON_KEY" \
  | jq '.definitions.post_faqs.properties | keys'

["answer_text","created_at","id","position","post_id","question"]

On our project that response is 31,780 bytes and lists all 7 exposed tables with every column the cache knows. This is the arbiter. If the column you are writing appears in that list, the cache is current and the bug is in your request; no reload will change anything, as it would not have for my post_slug. If the column exists in the database but is missing from this dump, you finally have the real thing: a stale cache, and you are in #42183 territory rather than typo territory. The same dump would have answered our 1,000-row default surprise faster than the docs did.

When it really is the cache

The documented remedy is a NOTIFY from any SQL session: NOTIFY pgrst, 'reload schema';. On Supabase you should rarely need it, because the platform installs event triggers (pgrst_ddl_watch, pgrst_drop_watch) that fire that NOTIFY automatically after DDL. Two details keep me from calling it a non-issue. First, Supabase’s own lint tooling has an open proposal to detect when those triggers are missing, which is an acknowledgment that they can go missing. Second, in both GitHub issues above the reporters ran the NOTIFY themselves and the errors survived it, along with pause/resume in one case and drop-and-recreate in the other.

Honesty about the limits of my data: I could not reproduce a genuinely stale cache on our project. This rig holds REST keys only — the same split I relied on when testing RLS with the anon key — and has no SQL path from which to run DDL, so I cannot alter a table and time how fast the triggers repopulate the cache. What I can say from the probes is narrower but useful: in every failure mode I could produce, the cache was innocent and the request was guilty, and the OpenAPI dump proved it in one command. We normalized the Storage API’s error codes the same way last month; the Data API turns out to deserve the same treatment.

FAQ

What does PGRST204 mean in Supabase?

PostgREST, the server behind Supabase’s Data API, could not find a column named in your INSERT or UPDATE body (or ?columns= parameter) in its cached copy of the schema. It returns HTTP 400 before any SQL runs. Most often the name is wrong in the request; less often the cache is stale after schema changes.

Why does a select return 42703 but an insert returns PGRST204 for the same column?

Column names in select, filters, and order are compiled into SQL and rejected by PostgreSQL itself (SQLSTATE 42703). Body keys in writes are validated against PostgREST’s schema cache before any statement is built, so the same wrong name fails earlier, with PostgREST’s own code.

How do I reload the PostgREST schema cache in Supabase?

Run NOTIFY pgrst, 'reload schema'; in the SQL editor. Supabase normally does this automatically via DDL event triggers, so if PGRST204 persists, first compare the column list in GET /rest/v1/ against your actual table; if the column is in the dump, the cache is not your problem.

Method and sources: every probe above ran on 2026-08-28 against this site’s production Supabase project, using requests designed to fail (columns, tables, and functions that have never existed), so nothing was written. Error JSON is quoted verbatim from those responses. The August 13 incident is from this site’s publishing log. Docs cited are the PostgREST v13 references; both Supabase GitHub issues were open when this was published. I could not reproduce a genuinely stale cache from this machine (it deliberately holds REST credentials only), so the staleness half rests on the linked documentation and issue reports, not on my measurements.