22021 — character_not_in_repertoire

A source byte sequence is invalid for the encoding being checked. The fixed conversion path reports invalid byte sequence for encoding "%s": %s and formats the offending bytes.

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: character_not_in_repertoire
lang: en
sqlstate: 22021

Definition PG 18

22021

At a glance {#at-a-glance}

A source byte sequence is invalid for the encoding being checked. The fixed conversion path reports invalid byte sequence for encoding "%s": %s and formats the offending bytes.

Meaning {#meaning}

report_invalid_encoding computes the incomplete or invalid multibyte length and emits 22021 with the source encoding name and hexadecimal bytes. A valid source character that has no equivalent in the destination encoding follows the separate 22P05 untranslatable-character path; that is not evidence that the source bytes themselves are malformed.

Diagnosis {#diagnosis}

Record source and destination encodings, client/database settings, and the exact bytes before changing anything. Invalid source bytes point to input or boundary decoding; a readable but unrepresentable character points to conversion repertoire. Do not treat SQL_ASCII as a universal fix: accepting arbitrary bytes can defer or hide an encoding boundary defect.

Response {#response}

Repair the producer or encoding boundary, or explicitly convert the value with a deliberate loss/rejection policy while retaining the offending bytes for diagnosis. If the ERROR occurred in an explicit transaction, roll back or roll back to the existing savepoint before retrying; autocommit can retry corrected input.

Versions {#versions}

The locked catalogue records this condition from 7.4; the fixed conversion paths here are PostgreSQL 18.6. No natural runtime observation is claimed for this page.

Related {#related}

22P05, 22018

Sources {#sources}

The invalid-byte reporter is src/backend/utils/mb/mbutils.c#L1818-1853; the same fixed file’s report_untranslatable_char path emits the distinct 22P05 condition for a valid but non-representable character. The structured evidence record retains both boundaries; no natural runtime was run.

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": "22021 is character_not_in_repertoire in SQLSTATE Class 22"
}

claims · resolved-path

{
  "claim_id": "resolved-path",
  "limits": "Source confirmation is not a natural runtime observation.",
  "method": "Read complete source contexts for the representative guards.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.mbutils.invalid",
    "src.mbutils.untranslatable"
  ],
  "statement": "Fixed PostgreSQL 18.6 encoding helpers distinguish invalid source bytes (22021) from a valid source character with no destination equivalent (22P05)."
}

claims · history

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

messages · message.invalid-byte

{
  "limits": "",
  "message_id": "message.invalid-byte",
  "path": "",
  "position": 0,
  "raw": {
    "id": "message.invalid-byte",
    "primary_template": "invalid byte sequence for encoding \"%s\": %s",
    "severity_source": "ERROR",
    "sources": [
      "src.mbutils.invalid"
    ],
    "sqlstate": "22021"
  },
  "severity": "ERROR",
  "sources": [
    "src.mbutils.invalid"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "invalid byte sequence for encoding \" \":",
      "position": 0,
      "role": "",
      "template": "invalid byte sequence for encoding \"%s\": %s"
    }
  ]
}

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#L165"
}

sources · src.mbutils.invalid

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/mb/mbutils.c",
  "position": 1,
  "sha256": "2c034d792a3fbc402d673d6e08bd6a2198651bfd3c057176d4098f7e4a215dfb",
  "source_id": "src.mbutils.invalid",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/mb/mbutils.c#L1818"
}

sources · src.mbutils.untranslatable

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/mb/mbutils.c",
  "position": 2,
  "sha256": "2c034d792a3fbc402d673d6e08bd6a2198651bfd3c057176d4098f7e4a215dfb",
  "source_id": "src.mbutils.untranslatable",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/mb/mbutils.c#L1861"
}

Source references

Original manual reference

Full definition and evidence JSON

Definition sources

center · PostgreSQL 18 · english-manuals:cb95654efd6bf18765485d42f13c533cde44d1844f1d10235fa846faed4d1c34

Text language: en · english-manuals:cb95654efd6bf18765485d42f13c533cde44d1844f1d10235fa846faed4d1c34