program_limit_exceeded row is too big: size N, maximum size N — 54000

Symptoms

A row’s on-page size exceeded the maximum a single page can store even after TOAST compression/out-of-line storage. PostgreSQL raises SQLSTATE 54000 (program_limit_exceeded).

• The message reports the row size and the 8160-ish maximum.
• Happens with many wide columns that can’t all be TOASTed.
• Often from many fixed-width or non-toastable columns.

What the server log shows

ERROR:  row is too big: size 8400, maximum size 8160

Why PostgreSQL raises this — what the manual says

Section 66.2 TOAST:

“PostgreSQL uses a fixed page size (commonly 8 kB), and does not allow tuples to span multiple pages.”

Each tuple must fit on one 8 kB page; TOAST moves large variable-length values out of line, but the main row plus non-toastable columns must still fit. When they don’t, PostgreSQL reports 54000.

Common causes

• A table with very many columns.
• Many fixed-width columns that cannot be TOASTed out of line.
• Wide values in types with limited storage strategies.

How to fix it

1. Normalize the table — split rarely-used wide columns into a related table.
2. Ensure large columns use TOAST-able types (e.g. text) with extended storage.
3. Reduce the number of columns or use a larger custom page size build (advanced).

Related & next steps

• SQLSTATE 54000 — Program Limit Exceeded (full reference)
• Message: index row size exceeds maximum
• Glossary: TOAST

Reference: PostgreSQL 18 Section 65.2 “TOAST”.