SQLSTATE / CLASS 22 · DATA EXCEPTION

22011

substring_error

SQLSTATE: 22011
Condition name: substring_error
Class: Data Exception
Source macro: ERRCODE_SUBSTRING_ERROR
Evidence: Source path confirmed

Analysis & operational context

English SQLSTATE atlas: authored explanations and source/runtime evidence are separate from the manual definitions. View source ↗

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.

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.

Source evidence

Evidence belongs to the frozen source and runtime versions listed here. It is not a runtime verification of the selected manual version.

22011 is substring_error in SQLSTATE Class 22.

Method: Read the fixed errcodes row and macro.

src.errcodes.18.6

The fixed text_substring path raises 22011 only for an explicit negative length; the omitted-length sentinel returns the remainder and the start/end calculations cover empty and overflow cases.

Method: Read the complete text_substring wrapper and guard.

Limits: This is the fixed text path; other substring data types have separate consumers.

src.text-substring.18.6

The fixed OVERLAY path reuses the 22011 primary for a non-positive start, while an overflowing start-plus-length uses 22003.

Method: Read the complete OVERLAY guard and overflow branch.

src.overlay.18.6

The locked catalogue records 22011 from 7.4 without proving an exact implementation introduction date.

Method: Use catalogue presence and history boundaries.

src.errcodes.18.6

src/backend/utils/errcodes.txt · REL_18_6 ·
724edf9bde9d356724ad384a2e196edc3c9f80f7
src/backend/utils/adt/varlena.c · REL_18_6 ·
724edf9bde9d356724ad384a2e196edc3c9f80f7
src/backend/utils/adt/varlena.c · REL_18_6 ·
724edf9bde9d356724ad384a2e196edc3c9f80f7

Message templates

ERROR · message.text-negative-length

Primary

negative substring length not allowed

Explicit negative text length.

ERROR · message.overlay-nonpositive-start

Primary

negative substring length not allowed

Non-positive OVERLAY start; this is not the OVERLAY overflow branch.

Reproduction & repair cases

No reproduction case is attached to this condition.

Recorded runtime evidence

No runtime observation is attached to this entry.

Definition snapshot: english-manuals:d38108685a0492d8fa65a0237cd… · English manual source