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