// Referência de erro do PostgreSQL

PostgreSQL 22021: sequência de bytes inválida para a codificação

O texto contém bytes que não são válidos na codificação do banco de dados ou do cliente: um arquivo Latin-1 ou Windows-1252 carregado como UTF-8, ou um byte NUL no texto.

SQLSTATE
22021
Nome
character_not_in_repertoire
Categoria
Exceção de dados
Mensagem de erro
invalid byte sequence for encoding "UTF8": 0xff

O que significa

O PostgreSQL verifica se cada valor de texto é válido na codificação em que ele chega. 22021 (character_not_in_repertoire) significa que uma sequência de bytes não é um caractere válido nela. Com um banco de dados UTF-8, geralmente significa que os dados estavam de fato em outra codificação, como Latin-1 ou Windows-1252, em que bytes como 0xe9 (é) são bytes únicos que não são válidos em UTF-8 por si só.

Os tipos de texto do PostgreSQL nunca podem conter o byte NUL, então invalid byte sequence for encoding "UTF8": 0x00 significa que dados binários ou de string C alcançaram uma coluna de texto.

Causas comuns

  • Carregando um CSV exportado por uma ferramenta que usou Windows-1252 ou Latin-1, com COPY ou \copy assumindo UTF-8.
  • client_encoding definido para UTF8 enquanto o cliente na verdade envia outra codificação.
  • Dados binários, ou strings com bytes NUL incorporados, inseridos em um text ou varchar coluna.
  • Dados truncados no meio de um caractere multibyte por um aplicativo.

Como corrigir

  1. Conte COPY a codificação real do arquivo; o PostgreSQL a converte.

    \copy customers FROM 'customers.csv' WITH (FORMAT csv, HEADER true, ENCODING 'WIN1252')
  2. Ou configure a codificação de cliente da sessão para corresponder ao que o cliente envia.

    SET client_encoding = 'LATIN1';
  3. Converta o arquivo antes de carregar, por exemplo iconv -f WINDOWS-1252 -t UTF-8 in.csv > out.csv.

  4. Armazenar dados binários em bytea, e remover bytes NUL do texto no aplicativo antes de inserir.

Erros relacionados

Mais erros de exceção de dados

O código e o texto da mensagem são de documentação do PostgreSQL, Apêndice A: Códigos de erro do PostgreSQL. Veja toda a Lista de erros do PostgreSQL ou pesquise todos os erros do banco de dados.

// menos erros, correções mais rápidas

Trabalhe com PostgreSQL no SQLly

Um cliente SQL nativo para macOS, Windows e Linux com IntelliSense que conhece o esquema, proteções para instruções arriscadas e mensagens de erro claras, para o PostgreSQL e os outros bancos de dados que você usa.