22011 — substring_error

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.

English manual coverage begins with PostgreSQL 8.1. Source history and runtime observations have their own recorded version boundaries.

Reading PG 18·Select a recorded version

8.1 8.2 8.3 8.4 9.0 9.1 9.2 9.3 9.4 9.5 9.6 10 11 12 13 14 15 16 17 18 19 20

aliases: Unknown
class name: Data Exception
condition name: substring_error
lang: en
sqlstate: 22011

Definition PG 18

At a glance {#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 {#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 {#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 {#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 {#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 {#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 {#related}

22000, 22001, 22003

Sources {#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.

Compare versions

SQLSTATE evidence and recorded runtime versions

claims · identity

{
  "claim_id": "identity",
  "limits": "",
  "method": "Read the fixed errcodes row and macro.",
  "position": 0,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "22011 is substring_error in SQLSTATE Class 22."
}

claims · resolved-text-path

{
  "claim_id": "resolved-text-path",
  "limits": "This is the fixed text path; other substring data types have separate consumers.",
  "method": "Read the complete text_substring wrapper and guard.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.text-substring.18.6"
  ],
  "statement": "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."
}

claims · resolved-overlay-path

{
  "claim_id": "resolved-overlay-path",
  "limits": "",
  "method": "Read the complete OVERLAY guard and overflow branch.",
  "position": 2,
  "runtime": [],
  "sources": [
    "src.overlay.18.6"
  ],
  "statement": "The fixed OVERLAY path reuses the 22011 primary for a non-positive start, while an overflowing start-plus-length uses 22003."
}

claims · history

{
  "claim_id": "history",
  "limits": "",
  "method": "Use catalogue presence and history boundaries.",
  "position": 3,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "The locked catalogue records 22011 from 7.4 without proving an exact implementation introduction date."
}

messages · message.text-negative-length

{
  "limits": "Explicit negative text length.",
  "message_id": "message.text-negative-length",
  "path": "",
  "position": 0,
  "raw": {
    "id": "message.text-negative-length",
    "limits": "Explicit negative text length.",
    "primary_template": "negative substring length not allowed",
    "severity_source": "ERROR",
    "sources": [
      "src.text-substring.18.6"
    ],
    "sqlstate": "22011"
  },
  "severity": "ERROR",
  "sources": [
    "src.text-substring.18.6"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "negative substring length not allowed",
      "position": 0,
      "role": "",
      "template": "negative substring length not allowed"
    }
  ]
}

messages · message.overlay-nonpositive-start

{
  "limits": "Non-positive OVERLAY start; this is not the OVERLAY overflow branch.",
  "message_id": "message.overlay-nonpositive-start",
  "path": "",
  "position": 1,
  "raw": {
    "id": "message.overlay-nonpositive-start",
    "limits": "Non-positive OVERLAY start; this is not the OVERLAY overflow branch.",
    "primary_template": "negative substring length not allowed",
    "severity_source": "ERROR",
    "sources": [
      "src.overlay.18.6"
    ],
    "sqlstate": "22011"
  },
  "severity": "ERROR",
  "sources": [
    "src.overlay.18.6"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "negative substring length not allowed",
      "position": 0,
      "role": "",
      "template": "negative substring length not allowed"
    }
  ]
}

sources · src.errcodes.18.6

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/errcodes.txt",
  "position": 0,
  "sha256": "6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba",
  "source_id": "src.errcodes.18.6",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/errcodes.txt#L180"
}

sources · src.text-substring.18.6

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/varlena.c",
  "position": 1,
  "sha256": "fd4fa7e214370cabeec0a33792533e4f10037ba763ca1c433ae8795f9f04cd3c",
  "source_id": "src.text-substring.18.6",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/varlena.c#L896-1010"
}

sources · src.overlay.18.6

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/varlena.c",
  "position": 2,
  "sha256": "fd4fa7e214370cabeec0a33792533e4f10037ba763ca1c433ae8795f9f04cd3c",
  "source_id": "src.overlay.18.6",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/varlena.c#L1166-1186"
}

Source references

Original manual reference

Full definition and evidence JSON

Definition sources

center · PostgreSQL 18 · english-manuals:cb848e6212751c16d95ca7d93968f07d40c77f94cce3926b2c0994005e1e8880

Text language: en · english-manuals:cb848e6212751c16d95ca7d93968f07d40c77f94cce3926b2c0994005e1e8880