SQLSTATE / CLASS 22 · DATA EXCEPTION

22021

character_not_in_repertoire

SQLSTATE: 22021
Condition name: character_not_in_repertoire
Class: Data Exception
Source macro: ERRCODE_CHARACTER_NOT_IN_REPERTOIRE
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 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.

src.errcodes.18.6

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.

src.mbutils.invalid src.mbutils.untranslatable

The locked catalogue records 22021 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/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:d590469191c1067ae7b09ecbe98… · English manual source