// PostgreSQL 錯誤參考

PostgreSQL 22021:編碼的位元組序列無效

文字包含資料庫或用戶端編碼中無效的位元組:例如把 Latin-1 或 Windows-1252 檔案當成 UTF-8 載入,或文字裡有 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 客戶端,具備結構描述感知的 IntelliSense、高風險陳述式防護與清楚的錯誤訊息,適用於 PostgreSQL 和你使用的其他資料庫。