// PostgreSQL 错误参考
PostgreSQL 22021:编码的字节序列无效
文本包含在数据库或客户端编码中无效的字节:作为 UTF-8 加载的 Latin-1 或 Windows-1252 文件,或文本中的 NUL 字节。
- SQLSTATE
22021- 名称
character_not_in_repertoire- 类别
- 数据异常
它的意思
PostgreSQL 会检查收到的每个文本值在其编码下是否有效。22021 (character_not_in_repertoire)意味着某个字节序列在该处不是有效字符。在 UTF-8 数据库中,这通常意味着数据实际上是另一种编码,例如 Latin-1 或 Windows-1252,其中像 0xe9 (é)这样的字节是单字节,在 UTF-8 中单独存在时无效。
PostgreSQL 文本类型永远不能包含 NUL 字节,所以 invalid byte sequence for encoding "UTF8": 0x00 表示二进制或 C 字符串数据进入了文本列。
常见原因
- 加载由按 Windows-1252 或 Latin-1 编码写出的工具导出的 CSV,并
COPY或者\copy假定为 UTF-8。 client_encoding设置为UTF8而客户端实际发送的是另一种编码。- 二进制数据,或含嵌入 NUL 字节的字符串,插入到一个
text或者varchar列。 - 应用程序在多字节字符中间截断了数据。
如何修复它
-
告诉
COPY文件的真实编码;PostgreSQL 会进行转换。\copy customers FROM 'customers.csv' WITH (FORMAT csv, HEADER true, ENCODING 'WIN1252')
-
或者为会话设置客户端编码,使其与客户端发送的编码匹配。
SET client_encoding = 'LATIN1';
-
在加载之前转换文件,例如
iconv -f WINDOWS-1252 -t UTF-8 in.csv > out.csv. -
将二进制数据存储在
bytea,并在插入前先在应用程序中剔除文本里的 NUL 字节。
相关错误
更多数据异常错误
代码和消息文本来自 PostgreSQL 文档,附录 A:PostgreSQL 错误代码。浏览完整的 PostgreSQL 错误列表 或者 搜索每个数据库错误.
// 错误更少,修复更快
在 SQLly 中使用 PostgreSQL
适用于 macOS、Windows 和 Linux 的原生 SQL 客户端,智能感知能理解你的数据库模式,高危语句有防护,错误信息清晰,支持 PostgreSQL 以及你使用的其他数据库。