// Referencia de errores de PostgreSQL

PostgreSQL 22021: secuencia de bytes no válida para la codificación

El texto contiene bytes que no son válidos en la codificación de la base de datos o del cliente: un archivo Latin-1 o Windows-1252 cargado como UTF-8, o un byte NUL en el texto.

SQLSTATE
22021
Nombre
character_not_in_repertoire
Categoría
Excepción de datos
Mensaje de error
invalid byte sequence for encoding "UTF8": 0xff

Qué significa

PostgreSQL verifica que cada valor de texto sea válido en la codificación en la que llega. 22021 (character_not_in_repertoire) significa que una secuencia de bytes no es un carácter válido allí. Con una base de datos UTF-8, normalmente significa que los datos estaban en realidad en otra codificación, como Latin-1 o Windows-1252, donde bytes como 0xe9 (é) son bytes individuales que por sí solos no son UTF-8 válido.

Los tipos de texto de PostgreSQL nunca pueden contener el byte NUL, así que invalid byte sequence for encoding "UTF8": 0x00 significa que datos binarios o de tipo C-string llegaron a una columna de texto.

Causas comunes

  • Cargando un CSV exportado por una herramienta que escribió en Windows-1252 o Latin-1, con COPY o \copy asumiendo UTF-8.
  • client_encoding establecido en UTF8 mientras que el cliente en realidad envía otra codificación.
  • Datos binarios, o cadenas con bytes NUL incrustados, insertados en un text o varchar columna.
  • Datos truncados en medio de un carácter de varios bytes por una aplicación.

Cómo solucionarlo

  1. Indica COPY la codificación real del archivo; PostgreSQL la convierte.

    \copy customers FROM 'customers.csv' WITH (FORMAT csv, HEADER true, ENCODING 'WIN1252')
  2. O establece la codificación de cliente de la sesión para que coincida con lo que envía el cliente.

    SET client_encoding = 'LATIN1';
  3. Convierte el archivo antes de cargarlo, por ejemplo iconv -f WINDOWS-1252 -t UTF-8 in.csv > out.csv.

  4. Guarda datos binarios en bytea, y eliminar bytes NUL del texto en la aplicación antes de insertar.

Errores relacionados

Más errores de excepción de datos

El código y el texto del mensaje son de documentación de PostgreSQL, Apéndice A: Códigos de error de PostgreSQL. Explora la lista completa de Lista de errores de PostgreSQL o buscar cada error de base de datos.

// menos errores, correcciones más rápidas

Trabajar con PostgreSQL en SQLly

Un cliente SQL nativo para macOS, Windows y Linux con IntelliSense que conoce el esquema, protecciones para las instrucciones de riesgo y mensajes de error claros, para PostgreSQL y las demás bases de datos que uses.