program_limit_exceeded index row size N exceeds maximum N for index “…” — 54000

Symptoms

An attempt to index a value produced a B-tree index entry larger than the per-entry maximum (about one third of a page). PostgreSQL raises SQLSTATE 54000 (program_limit_exceeded).

• An index tuple exceeds the B-tree size limit.
• Common when indexing long text/bytea values directly.
• Btree entries must fit within roughly 1/3 of a page.

What the server log shows

ERROR:  index row size 2992 exceeds btree version 4 maximum 2704 for index "idx_docs_body"

Why PostgreSQL raises this — what the manual says

the B-Tree Indexes documentation (Implementation):

“The only limitation is that an index entry cannot exceed approximately one-third of a page (after TOAST compression, if applicable).”

B-tree entries must fit several per page, so a single entry cannot exceed roughly a third of a page. Indexing a very large value produces an oversized entry, so PostgreSQL reports 54000.

Common causes

• Building a B-tree index on long text/bytea columns.
• Unique constraints on very large values.
• Concatenated multi-column keys that are too wide.

How to fix it

1. Index a hash of the value (e.g. an expression index on md5(col) or a hash index).
2. Index only a prefix: CREATE INDEX … ON t (left(col, 100)).
3. Use full-text search (GIN/tsvector) for large text instead of a B-tree.

Related & next steps

• SQLSTATE 54000 — Program Limit Exceeded (full reference)
• Message: tables can have at most 1600 columns
• Glossary: B-tree

Reference: PostgreSQL 18 Section 64.1 “B-Tree”.