SQLSTATE / Class 22 · Data Exception
22021
Read the PG 18 manualcharacter_not_in_repertoire
Reading PG 18current·documented in 22 of 22 versions, 8.1 to 20
- SQLSTATE
- 22021
- Condition name
- character_not_in_repertoire
- Class
- Data Exception
- Source macro
- ERRCODE_CHARACTER_NOT_IN_REPERTOIRE
- Evidence
- Source path confirmed
English SQLSTATE atlas: authored explanations and source/runtime evidence are separate from the manual definitions. View source
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
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
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
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
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.
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.
Source evidence
Evidence belongs to the frozen source and runtime versions listed here. It is not a runtime verification of the selected manual version.
22021 is character_not_in_repertoire in SQLSTATE Class 22
Method: Read the fixed errcodes row and macro.
Fixed PostgreSQL 18.6 encoding helpers distinguish invalid source bytes (22021) from a valid source character with no destination equivalent (22P05).
Method: Read complete source contexts for the representative guards.
Limits: Source confirmation is not a natural runtime observation.
Source: src/backend/utils/mb/mbutils.c · Source: src/backend/utils/mb/mbutils.c
The locked catalogue records 22021 from 7.4 without proving an exact implementation introduction date.
Method: Use catalogue presence and history boundaries.
- src/backend/utils/errcodes.txt · REL_18_6 ·
724edf9bde9d356724ad384a2e196edc3c9f80f7 - src/backend/utils/mb/mbutils.c · REL_18_6 ·
724edf9bde9d356724ad384a2e196edc3c9f80f7 - src/backend/utils/mb/mbutils.c · REL_18_6 ·
724edf9bde9d356724ad384a2e196edc3c9f80f7
Message templates
ERROR · message.invalid-byte
Primary
invalid byte sequence for encoding "%s": %s
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:cb95654efd6bf18765485d42f13… · English manual source