Base64-Dekodierfehler und wie Sie sie beheben

Fehlermeldungen im Überblick

Decoder-Fehler beheben

„Incorrect padding“ in Python

Base64-Ausgaben haben immer eine durch 4 teilbare Länge, aufgefüllt mit = am Ende. Der Decoder von Python verlangt das Padding:

>>> import base64
>>> base64.b64decode("SGVsbG8")
Traceback (most recent call last):
  ...
binascii.Error: Incorrect padding
>>> base64.b64decode("SGVsbG8=")
b'Hello'

Fehlendes Padding bedeutet meist, dass der String Base64URL ist (JWTs, URL-Tokens und viele APIs lassen = weg) oder dass etwas ihn gekürzt hat. Ergänzen Sie das Padding:

s = "SGVsbG8"
s += "=" * (-len(s) % 4)

Ist die Länge um eins größer als ein Vielfaches von 4, hilft kein Padding. Python meldet dann number of data characters (5) cannot be 1 more than a multiple of 4. Ein einzelnes übrig gebliebenes Zeichen enthält nur 6 Bit, ein Teil der Daten fehlt also. Diese Meldung erscheint auch ohne abgeschnittene Zeichenkette: Ohne validate=True verwirft Python Zeichen außerhalb des Alphabets, darunter - und _. base64.b64decode("SGk_Pg==") verwirft das _ und landet bei 5 Datenzeichen. Verwenden Sie für Base64URL-Eingaben base64.urlsafe_b64decode.

„Invalid character“ und Fehler bei atob

Browser implementieren atob mit demselben Algorithmus, formulieren den Fehler aber unterschiedlich. Chrome meldet „The string to be decoded is not correctly encoded“, Firefox „String contains an invalid character“, Node.js „Invalid character“. Alle drei werfen bei diesen Eingaben einen InvalidCharacterError:

• Base64URL-Zeichen. atob("SGk_Pg") scheitert am _. Ersetzen Sie zuerst - durch + und _ durch /.
• Eine Länge von 4n+1 nach dem Entfernen von Leerraum, etwa bei atob("A").
• Zeichen, die nicht dazugehören: aus JSON mitkopierte Anführungszeichen, ein data:-Präfix, ein %2F aus der URL-Kodierung.

Manches verzeiht atob auch. Es überspringt Leerzeichen und Zeilenumbrüche und akzeptiert fehlendes Padding, wenn die Länge aufgeht, atob("SGVsbG8") liefert also "Hello". Der spiegelbildliche Fehler, btoa mit „characters outside of the Latin1 range“, betrifft Unicode-Text und wird unter Uint8Array.toBase64 behandelt.

Ein toleranter Decoder, der beide Alphabete, Leerraum und fehlendes Padding verkraftet:

function decodeLoose(s) {
  s = s.replace(/\s+/g, "").replace(/-/g, "+").replace(/_/g, "/");
  s += "=".repeat((4 - (s.length % 4)) % 4);
  return Uint8Array.from(atob(s), (c) => c.charCodeAt(0));
}

new TextDecoder().decode(decodeLoose("SGk_Pg")); // "Hi?>"

Das Gegenstück in Python:

import base64

def b64decode_any(s: str) -> bytes:
    s = "".join(s.split())
    s = s.replace("-", "+").replace("_", "/")
    s += "=" * (-len(s) % 4)
    return base64.b64decode(s, validate=True)

Das Tool Base64 reparieren führt dieselbe Bereinigung durch und zeigt, was es geändert hat.

„Illegal base64 character“ in Java und FormatException in .NET

java.util.Base64 bringt drei Decoder mit, und jeder ist bei seinem eigenen Alphabet streng. Die Meldung nennt das fehlerhafte Zeichen in Hex: 5f ist _, 2d ist -, 2f ist /, 20 ist ein Leerzeichen, a ist ein Zeilenumbruch.

Der Basis-Decoder lehnt Zeilenumbrüche und Leerzeichen ab. Fehlendes Padding akzeptiert er, SGVsbG8 wird also ohne Beanstandung dekodiert.

Convert.FromBase64String in .NET wirft bei Base64URL-Zeichen und fehlendem Padding eine FormatException. Leerzeichen und Zeilenumbrüche überspringt es. Korrigieren Sie Alphabet und Padding wie oben gezeigt, bevor Sie es aufrufen. Vollständige Beispiele stehen unter Base64 in Java und Base64 in C#.

Der Text kommt als Zeichensalat heraus

Das Dekodieren hat geklappt, aber der Text sieht falsch aus. Base64 speichert Bytes, und diese Bytes wurden mit einer bestimmten Zeichenkodierung aus Text erzeugt. Liest man sie mit einer anderen zurück, entsteht Zeichensalat (Mojibake).

Die erste Zeile ist die klassische atob-Falle. atob("Q2Fmw6k=") liefert "Café", weil atob jedes Byte auf ein Zeichen abbildet. Dekodieren Sie die Bytes stattdessen als UTF-8:

const bytes = Uint8Array.from(atob("Q2Fmw6k="), (c) => c.charCodeAt(0));
new TextDecoder().decode(bytes); // "Café"

UTF-16LE ist bei Windows-Tools verbreitet: -EncodedCommand von PowerShell und viele .NET-APIs erzeugen es. Mit Base64 in Text wechseln Sie den Zeichensatz, bis die Ausgabe stimmt, und Base64 in UTF-16 kümmert sich um den Fall mit breiten Zeichen.

Die Ausgabe sieht binär aus

Ist das dekodierte Ergebnis voller �, Steuerzeichen oder Fragmente wie PNG, PK und %PDF, ist die Payload eine Datei. Sehen Sie sich die ersten Zeichen des Base64 an: iVBORw0KGgo ist ein PNG, JVBERi0 ein PDF, H4sI gzip. Die vollständige Liste steht unter Häufige Base64-Präfixe. Öffnen Sie die Daten mit Base64 in Datei, das das Format erkennt und einen Download anbietet. Für H4sI verwenden Sie gzip-Base64 dekodieren.

Das Dekodieren liefert andere Bytes als erwartet

Kein Fehler, aber die Bytes stimmen nicht. Das sind die üblichen Gründe:

• Ein abschließender Zeilenumbruch beim Kodieren. echo "hello" | base64 ergibt aGVsbG8K (mit \n), echo -n "hello" | base64 dagegen aGVsbG8=. Verwenden Sie printf '%s' oder echo -n.
• Aus + wurde ein Leerzeichen. In URL-Query-Strings und Formulardaten bedeutet + ein Leerzeichen. URLSearchParams("t=PGI+Ym9sZDwvYj4=").get("t") liefert PGI Ym9sZDwvYj4=. Manche Decoder werfen dann einen Fehler, andere verwerfen das Leerzeichen und erzeugen Datenmüll. Prozentkodieren Sie Base64 mit encodeURIComponent, bevor Sie es in eine URL setzen, oder verwenden Sie Base64URL.
• Prozentkodierung nicht entfernt. SGk%2FPg%3D%3D muss vor dem Base64-Dekodieren per URL-Dekodierung zu SGk/Pg== werden.
• Aus JSON kopierte Escapes. Kopiert man einen String aus rohem JSON, kann ein literales \n (zwei Zeichen) mitkommen. Der tolerante Decoder von Python verwirft den Backslash, behält das n und liefert ohne Fehler falsche Bytes: b64decode("SGVs\\nbG8=") ergibt b'Hel\x9d\xb1\xbc'. Parsen Sie das JSON, statt daraus zu kopieren. Der JSON-Base64-Decoder macht das für jedes Feld.
• Strenger oder toleranter Umgang mit Leerraum. Python ohne validate=True, atob, .NET und der MIME-Decoder von Java überspringen Zeilenumbrüche. Python mit validate=True und der Basis-Decoder von Java lehnen sie ab. MIME- und PEM-Daten sind nach 76 oder 64 Zeichen umgebrochen, wählen Sie also einen Decoder, der das akzeptiert.

Doppelt kodierte Daten

Das Dekodieren von U0dWc2JHOGdkMjl5YkdRaA== ergibt SGVsbG8gd29ybGQh, was wieder gültiges Base64 ist und zu Hello world! dekodiert wird. Besteht das Ergebnis eines Dekodiervorgangs nur aus Base64-Zeichen und ist seine Länge ein Vielfaches von 4, liegt der Verdacht auf doppelte Kodierung nahe.

Bei Kubernetes-Secrets passiert das oft. Werte unter data: sind Base64, und kubectl create secret --from-literal kodiert für Sie. Kodieren Sie den Wert vorher selbst, erhält der Pod Base64-Text statt des Passworts. Verwenden Sie stringData: für Klartextwerte oder prüfen Sie mit dem Kubernetes-Secret-Decoder, was gespeichert ist. Im Zweifel zeigt der Base64-Validator, ob ein String gültig ist und wie viele Bytes er enthält.

Häufige Fragen