„Unexpected token“ klingt nach einem einfachen Syntaxfehler. In Produktion kann die Ursache jedoch weit vor dem Parser liegen: Ein Proxy liefert eine HTML-Fehlerseite, ein Stream endet zu früh, ein Log fügt Text hinzu oder Bytes werden mit dem falschen Zeichensatz gelesen. Erfolgreiche Fehlersuche beginnt deshalb nicht mit zufälligem Ersetzen von Kommas, sondern mit der exakten Eingabe an der betroffenen Grenze.

Zuerst die tatsächlich empfangenen Bytes sichern

Die Darstellung in einer Konsole kann Escape-Zeichen interpretieren, lange Werte abschneiden oder Steuerzeichen unsichtbar machen. Für einen reproduzierbaren Befund braucht man Body-Länge, Content-Type und möglichst eine sichere Kopie der rohen Bytes. Sensible Daten müssen dabei redigiert und kurz aufbewahrt werden.

Ein Hexdump rund um die Fehlerposition zeigt Byte Order Marks, Nullbytes, ungültiges UTF-8 und unerwartete Zeilenenden. Erst danach ist klar, ob wirklich JSON beim Parser angekommen ist.

HTML statt JSON ist ein häufiger Produktionsfehler

Load Balancer, Auth-Gateways und Webserver erzeugen eigene Fehlerseiten. Der Client erwartet JSON und meldet beim ersten < einen Parserfehler. Die eigentliche Ursache kann ein 502, ein Login-Redirect oder ein Größenlimit sein. Statuscode, Redirect-Kette und Content-Type gehören daher immer zur Diagnose.

Clients sollten vor dem Parsen prüfen, ob der Response-Typ zum Vertrag passt. Bei Abweichung ist eine kurze, sicher redigierte Vorschau hilfreicher als die irreführende Behauptung, der Server habe lediglich ungültiges JSON gesendet.

Abgeschnittene Dokumente zeigen sich oft am Ende

Fehlt eine schließende Klammer, muss nicht der Producer sie vergessen haben. Timeouts, unterbrochene Verbindungen, falsch berechnete Content-Length oder ein voller Zwischenspeicher können einen gültigen Body verkürzen. Ein Vergleich von erwarteter und empfangener Länge sowie Server- und Proxy-Logs grenzt das Problem ein.

Retries helfen nur, wenn die Operation sicher wiederholbar ist. Bei Schreibrequests braucht es Idempotenz, sonst kann ein Client nach einer unvollständigen Antwort dieselbe fachliche Aktion doppelt auslösen.

Trailing Commas und Kommentare gehören nicht zu JSON

JavaScript-Objektliterale und manche Konfigurationsformate erlauben Kommentare, einfache Anführungszeichen oder ein Komma nach dem letzten Element. Standard-JSON tut das nicht. Daten, die in einem Editor plausibel aussehen, können deshalb von einem korrekten Parser abgelehnt werden.

Ein toleranter Parser ist nicht immer die beste Lösung. Wenn eine API JSON verspricht, sollte der Producer korrigiert werden. Für von Menschen gepflegte Konfiguration kann dagegen JSON5, YAML oder ein anderes bewusst gewähltes Format geeigneter sein.

Strings scheitern häufig an Escape-Regeln

Ein Zeilenumbruch darf nicht roh innerhalb eines JSON-Strings stehen; Anführungszeichen und Backslashes müssen escaped werden. Probleme entstehen oft, wenn Code JSON per Stringverkettung erzeugt. Ein Benutzername mit Anführungszeichen oder ein Windows-Pfad reicht dann, um die Struktur zu zerstören.

Serialisierungsbibliotheken sollten Datenstrukturen in JSON umwandeln. Templates und manuelle Ersetzungen können nicht zuverlässig alle Steuerzeichen, Unicode-Fälle und Verschachtelungen behandeln. Dasselbe gilt für SQL, HTML und andere kontextabhängige Formate.

Ungültiges UTF-8 ist kein gewöhnlicher Syntaxfehler

JSON-Text wird im Web üblicherweise als UTF-8 übertragen. Kommen Bytes aus einer Legacy-Datenbank oder Datei, können sie in Windows-1252 oder einer anderen Codierung vorliegen. Ein Parser lehnt die Eingabe ab oder ein früherer Schritt ersetzt Zeichen stillschweigend.

Die richtige Korrektur liegt an der Quelle oder einer klaren Importgrenze. Mehrfaches Ausprobieren verschiedener Decodings kann Daten verändern. Pipeline, Datenbankverbindung und HTTP-Header sollten denselben Zeichensatzvertrag besitzen.

Doppelte Serialisierung erzeugt gültiges, aber falsches JSON

Manchmal meldet der Parser keinen Fehler, doch statt eines Objekts entsteht ein String, der wiederum JSON enthält. Das passiert, wenn eine Schicht bereits serialisiert und eine zweite denselben Wert erneut serialisiert. Sichtbare Backslashes vor jedem Anführungszeichen sind ein typisches Signal.

Die Lösung ist nicht pauschal zweimal zu parsen. Der Vertrag muss festlegen, ob eine Funktion strukturierte Daten oder fertigen JSON-Text erhält. Doppelte Decodierung kann sonst Inhalte interpretieren, die absichtlich nur Text sein sollten.

Doppelte Schlüssel sind semantisch gefährlich

Ein Objekt mit zwei gleichnamigen Eigenschaften wird von Bibliotheken unterschiedlich behandelt: Manche behalten den letzten Wert, andere den ersten, weitere lehnen es ab. Sicherheitsprüfungen und Geschäftslogik können dadurch verschiedene Werte sehen. Ein Angreifer nutzt die Parser-Differenz statt ungültiger Syntax.

An Vertrauensgrenzen ist Ablehnung doppelter Schlüssel die klarste Policy. Producer sollten Objekte aus Maps oder typisierten Modellen serialisieren und nicht durch Zusammenfügen von Fragmenten erzeugen.

Große Zahlen können nach dem Parsen falsch werden

Ein Dokument kann formal gültig sein, während ein JavaScript-Client eine 64-Bit-ID rundet. Der Fehler erscheint später als nicht gefundenes Objekt oder falscher Cache-Key. Debugging muss daher neben Syntax auch den Wert nach der Konvertierung betrachten.

IDs außerhalb des sicheren Zahlenbereichs sollten als Strings reisen. Für Dezimalwerte braucht es eine vereinbarte Präzision. Testfälle müssen Grenzen enthalten, nicht nur kleine Beispielzahlen.

Parserpositionen brauchen Kontext

Eine Meldung mit Offset oder Zeile ist nur dann nützlich, wenn sie auf die unveränderte Eingabe bezogen wird. Pretty-Printing vor der Analyse verschiebt Positionen und kann bei bereits ungültigem JSON selbst scheitern. Ein kleines Fenster vor und nach dem Offset zeigt meist die verletzte Struktur.

Bei sehr langen einzeiligen Bodies helfen Werkzeuge, die Byte- und Zeichenspalten unterscheiden. Mehrbyte-UTF-8 kann sonst dazu führen, dass Editor und Parser verschiedene Positionen anzeigen.

Streaming-JSON braucht ein definiertes Framing

Mehrere JSON-Dokumente hintereinander sind ohne Trennregel nicht eindeutig. Systeme verwenden etwa NDJSON mit genau einem Dokument pro Zeile oder length-prefixed Frames. Ein gewöhnlicher Parser erwartet dagegen ein einzelnes vollständiges Top-Level-Dokument.

Wenn Logs vor oder nach dem Payload zusätzliche Zeilen schreiben, ist der Stream kein gültiges JSON mehr. Metadaten gehören in ein umschließendes Objekt oder in einen separat definierten Kanal.

Minimieren macht Fehler reproduzierbar

Nach dem Sichern der Originaleingabe kann man irrelevante Bereiche entfernen, bis der kleinste fehlerhafte Fall übrig bleibt. Diese Methode zeigt, ob ein bestimmtes Zeichen, eine Größe oder Verschachtelung den Fehler auslöst. Die minimierte Fixture gehört anschließend in einen Regressionstest.

Bei produktionsabhängigen Fehlern sollten außerdem Serverversion, Proxy-Pfad und Clientbibliothek festgehalten werden. Unterschiedliche Parseroptionen erklären häufig, warum derselbe Body nur in einem Teil der Umgebung scheitert.

Validierung folgt erst nach erfolgreichem Parsing

Syntaktisch gültiges JSON kann fachlich unbrauchbar sein: Pflichtfelder fehlen, Typen sind falsch oder Werte überschreiten Grenzen. Diese Fehler sollten als Schema- oder Validierungsprobleme gemeldet werden, nicht als Parserfehler. Eine präzise Trennung verkürzt Diagnose und liefert Clients handlungsfähige Antworten.

Der robuste Ablauf lautet: Transport prüfen, Bytes und Zeichensatz bestätigen, strikt parsen, Schema validieren und erst dann Geschäftsregeln ausführen. So wird aus einer vagen Meldung eine klar lokalisierte Vertragsverletzung, und die Korrektur landet an der richtigen Stelle der Pipeline.