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

Symptoms

A value being indexed produced an index entry larger than the maximum a B-tree index page can hold (roughly 1/3 of a page, about 2704 bytes). PostgreSQL raises SQLSTATE 54000 (program_limit_exceeded).

• Triggered by indexing very long text/bytea values.
• The message reports the offending size and the maximum.
• Affects B-tree indexes on large column values.

What the server log shows

ERROR:  index row size 3200 exceeds maximum 2704 for index "orders_notes_idx"

Why PostgreSQL raises this — what the manual says

As Section 11.2 Index Types explains:

A value being indexed produced a B-tree entry larger than the index can store (roughly one-third of a page), since B-tree pages cannot hold an entry that big; index a hashed or truncated expression of the column instead of the full value.

B-tree pages must hold at least a few entries, so a single index tuple cannot exceed about one third of a page. A value that produces a larger entry cannot be stored and PostgreSQL aborts with 54000.

Common causes

• Indexing a long text/bytea column directly.
• A composite index whose combined key is too wide.
• Storing large documents in an indexed column.

How to fix it

1. Index a hash or prefix instead: CREATE INDEX ON t (md5(notes)); or (left(notes, 100)).
2. Use a GIN index with full-text search (to_tsvector) for large text.
3. Reconsider whether the wide column needs a B-tree index at all.

Related & next steps

• SQLSTATE 54000 — Program Limit Exceeded (full reference)
• Message: row is too big
• Glossary: B-tree index

Reference: PostgreSQL 18 Section 11.2 “Index Types”.