// PostgreSQL 错误参考

PostgreSQL 22021:编码的字节序列无效

文本包含在数据库或客户端编码中无效的字节:作为 UTF-8 加载的 Latin-1 或 Windows-1252 文件,或文本中的 NUL 字节。

SQLSTATE
22021
名称
character_not_in_repertoire
类别
数据异常
错误信息
invalid byte sequence for encoding "UTF8": 0xff

它的意思

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 列。
  • 应用程序在多字节字符中间截断了数据。

如何修复它

  1. 告诉 COPY 文件的真实编码;PostgreSQL 会进行转换。

    \copy customers FROM 'customers.csv' WITH (FORMAT csv, HEADER true, ENCODING 'WIN1252')
  2. 或者为会话设置客户端编码,使其与客户端发送的编码匹配。

    SET client_encoding = 'LATIN1';
  3. 在加载之前转换文件,例如 iconv -f WINDOWS-1252 -t UTF-8 in.csv > out.csv.

  4. 将二进制数据存储在 bytea,并在插入前先在应用程序中剔除文本里的 NUL 字节。

相关错误

更多数据异常错误

代码和消息文本来自 PostgreSQL 文档,附录 A:PostgreSQL 错误代码。浏览完整的 PostgreSQL 错误列表 或者 搜索每个数据库错误.

// 错误更少,修复更快

在 SQLly 中使用 PostgreSQL

适用于 macOS、Windows 和 Linux 的原生 SQL 客户端,智能感知能理解你的数据库模式,高危语句有防护,错误信息清晰,支持 PostgreSQL 以及你使用的其他数据库。