// справочник ошибок 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-строки попали в текстовый столбец.

Распространённые причины

  • Загрузка CSV, экспортированного инструментом, который использовал Windows-1252 или Latin-1, с 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 или поиск по всем ошибкам баз данных.

// меньше ошибок, быстрее исправления

Работа с PostgreSQL в SQLly

Нативный SQL-клиент для macOS, Windows и Linux с IntelliSense, который знает вашу схему, предохранителями для рискованных запросов и понятными сообщениями об ошибках — для PostgreSQL и других баз данных, которые вы используете.