# 22021 — character_not_in_repertoire

> PostgreSQL SQLSTATE 22021 的来源与诊断参考。
---

# 22021

## 速览 {#at-a-glance}
源字节序列对于正在检查的编码无效。固定转换路径报告 `invalid byte sequence for encoding "%s": %s`，并以十六进制列出违规字节。

<!-- BEGIN SQLSTATE FACTS: generated by scripts/generate.py; do not edit -->

| 字段 | 值 |
| --- | --- |
| SQLSTATE | `22021` |
| 条件名 | `character_not_in_repertoire` |
| 状态 | `有效` |
| 已知存在于 | `7.4` |
| 锁定快照 | `9.0.23, 9.1.24, 9.2.24, 9.3.25, 9.4.26, 9.5.25, 9.6.24, 10.23, 11.22, 12.22, 13.23, 14.24, 15.19, 16.15, 17.11, 18.6, 19beta3` |
| 宏 | `ERRCODE_CHARACTER_NOT_IN_REPERTOIRE` |
| 别名 | `—` |

<!-- source facts: data/errcodes/22021.json -->
<!-- END SQLSTATE FACTS -->

## 含义 {#meaning}
`report_invalid_encoding` 计算不完整或无效多字节序列的长度，使用源编码名和十六进制字节发出 22021。有效的源字符若在目标编码中没有等价表示，则走独立的 `22P05` untranslatable-character 路径；这不表示源字节本身损坏。

## 诊断 {#diagnosis}
在改动前记录源/目标编码、客户端/数据库设置以及原始字节。无效源字节指向输入或边界解码问题；可读但不可表示的字符指向目标编码的字符表示范围。不要把 SQL_ASCII 当作无条件修复：接受任意字节可能只是推迟或隐藏编码边界缺陷。

## 处理 {#response}
修复生产端或编码边界，或在保留违规字节的前提下按明确的丢弃/拒绝策略显式转换。如果 ERROR 发生在显式事务中，应先 ROLLBACK 或回滚到既有保存点再重试；自动提交可重试修正后的输入。

## 版本 {#versions}
锁定目录从 7.4 起记录该条件；本页固定转换路径为 PostgreSQL 18.6。未声称本页有自然运行观察。

## 相关 {#related}
[`22P05`](../22p05/)、[`22018`](../22018/)

## 来源 {#sources}
无效字节报告器在 [`src/backend/utils/mb/mbutils.c#L1818-1853`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/mb/mbutils.c#L1818)；同一固定文件的 [`report_untranslatable_char` 路径](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/mb/mbutils.c#L1861)对有效但不可表示字符发出独立 22P05。结构化[证据记录](../../data/evidence/22021.json)保留两条边界；本页未运行自然案例。