// PostgreSQL-Fehlerreferenz

PostgreSQL 22021: ungültige Byte-Sequenz für die Codierung

Der Text enthält Bytes, die in der Datenbank- oder Client-Codierung nicht gültig sind: eine Latin-1- oder Windows-1252-Datei, die als UTF-8 geladen wurde, oder ein NUL-Byte im Text.

SQLSTATE
22021
Name
character_not_in_repertoire
Kategorie
Daten-Ausnahme
Fehlermeldung
invalid byte sequence for encoding "UTF8": 0xff

Was es bedeutet

PostgreSQL überprüft, dass jeder Textwert in der Codierung, in der er ankommt, gültig ist. 22021 (character_not_in_repertoire) bedeutet, dass eine Bytefolge dort kein gültiges Zeichen ist. In einer UTF-8-Datenbank heißt das meist, dass die Daten tatsächlich in einer anderen Kodierung wie Latin-1 oder Windows-1252 vorlagen, bei der Bytes wie 0xe9 (é) Einzelbytes sind, die für sich allein kein gültiges UTF-8 darstellen.

PostgreSQL-Texttypen können niemals das NUL-Byte enthalten, daher bedeutet invalid byte sequence for encoding "UTF8": 0x00 bedeutet, dass Binär- oder C-String-Daten in eine Textspalte gelangt sind.

Häufige Ursachen

  • Laden einer CSV, die von einem Tool mit Windows-1252 oder Latin-1 exportiert wurde, mit COPY oder \copy von UTF-8 ausgehend.
  • client_encoding gesetzt auf UTF8 während der Client tatsächlich eine andere Kodierung sendet.
  • Binärdaten oder Zeichenketten mit eingebetteten NUL-Bytes, eingefügt in ein text oder varchar Spalte hinzu.
  • Daten, die von einer Anwendung mitten in einem Mehrbyte-Zeichen abgeschnitten wurden.

Wie du es behebst

  1. Sag COPY die tatsächliche Kodierung der Datei mit; PostgreSQL konvertiert sie.

    \copy customers FROM 'customers.csv' WITH (FORMAT csv, HEADER true, ENCODING 'WIN1252')
  2. Oder stelle die Client-Kodierung für die Sitzung so ein, dass sie zu dem passt, was der Client sendet.

    SET client_encoding = 'LATIN1';
  3. Konvertiere die Datei vor dem Laden, zum Beispiel iconv -f WINDOWS-1252 -t UTF-8 in.csv > out.csv.

  4. Speichere Binärdaten in bytea, und entferne NUL-Bytes aus dem Text in der Anwendung, bevor du ihn einfügst.

Zugehörige Fehler

Weitere Fehler bei Daten-Exceptions

Der Code und der Meldungstext stammen aus der PostgreSQL-Dokumentation, Anhang A: PostgreSQL-Fehlercodes. Durchstöbere die vollständige PostgreSQL-Fehlerliste oder Jeden Datenbankfehler durchsuchen.

// weniger Fehler, schnellere Korrekturen

Arbeiten mit PostgreSQL in SQLly

Ein nativer SQL-Client für macOS, Windows und Linux mit schemabewusstem IntelliSense, Guardrails für riskante Anweisungen und klaren Fehlermeldungen, für PostgreSQL und die anderen Datenbanken, mit denen du arbeitest.