22011 — substring_error

At a glance

A text substring path received an invalid explicit length. In fixed PostgreSQL 18.6 code, text_substring reports negative substring length not allowed with SQLSTATE 22011.

Meaning

The three-argument text substring wrapper passes its explicit length to text_substring; a negative length reaches the ERRCODE_SUBSTRING_ERROR guard. The no-length wrapper instead passes a sentinel with length_not_specified, so it returns the remainder and does not enter that negative-length guard. The same code is also used by OVERLAY when its start position is non-positive. This evidence is for the text path: bytea, bit-string, and pattern-based substring operations have separate consumers and must be identified from the full diagnostic.

Diagnosis

Check the resolved operation and data type before changing values. For text, distinguish an explicit negative length from a start of zero or less: the source clamps the effective start to one and applies the SQL length adjustment. A start past the end returns an empty string. A large start-plus-length that overflows the 32-bit calculation runs to the end; it is not this error. In OVERLAY, a non-positive start uses the same primary, while an overflowing start-plus-length uses 22003 instead.

Response

Pass a non-negative explicit text length, or omit the length when the intended result is the remainder. Preserve the intended one-based start semantics and check the actual data type before applying a text-specific repair. This path raises ERROR; an explicit transaction must be rolled back or rolled back to an existing savepoint before retrying, while autocommit can retry only the corrected statement.

Messages

• Primary, ERROR: negative substring length not allowed for the explicit text substring guard and the non-positive OVERLAY start guard. There is no fixed DETAIL or HINT on these paths.

Versions

The locked catalogue records this condition from 7.4; fixed source coverage is PostgreSQL 18.6. The cited guards are current-version text and OVERLAY paths, not a claim about every substring implementation.

Related

22000, 22001, 22003

Sources

• src/backend/utils/adt/varlena.c#L896-L1010 contains the text wrappers, start adjustment, omitted-length sentinel, explicit negative-length ERROR, and end/overflow handling.
• src/backend/utils/adt/varlena.c#L1166-L1186 contains the OVERLAY guards and its distinct 22003 overflow branch.

Runtime verification is not_run; the source evidence is not a runtime observation. The structured evidence record retains the exact primary and source scope.