array subscript out of range

Symptoms

An array assignment used a subscript outside the allowed bounds, or an array grew beyond the maximum number of dimensions/size. PostgreSQL raises SQLSTATE 2202E (array_subscript_error).

• Reading an out-of-range subscript returns NULL; assigning out of range can error.
• Also appears when exceeding the maximum array dimensions.
• Common when building arrays by index in PL/pgSQL.

What the server log shows

ERROR:  array subscript out of range

Why PostgreSQL raises this — what the manual says

As Section 8.15 Arrays explains:

An array assignment or fixed-length context used a subscript outside the array’s current bounds; while reading an out-of-range subscript yields null, assigning beyond the allowed range raises this error.

PostgreSQL arrays allow sparse growth via assignment, but subscripts must remain within the supported integer range and dimension limit. A subscript beyond those limits is invalid and raises 2202E.

Common causes

• Assigning to a subscript far outside the current bounds.
• Exceeding the maximum number of array dimensions.
• Off-by-one logic in index-based array building.

How to fix it

1. Use sequential or bounded subscripts when extending arrays.
2. Build arrays with array_append()/array_agg() instead of arbitrary indexes.
3. Validate computed subscripts before assignment.

Related & next steps

• SQLSTATE 2202E — Array Subscript Error (full reference)
• Message: malformed array literal
• Glossary: Array

Reference: PostgreSQL 18 Section 8.15 “Arrays”.