Blog / Formatowanie JSON
🐛

Typowe błędy JSON i jak je naprawić

Przewodnik po błędach JSON, które faktycznie napotkasz w naturze - co znaczą, skąd się biorą i jak je szybko naprawić.

· 7min czytania

Każdy deweloper, który pracuje z JSON-em, w końcu uczy się jego komunikatów błędów na pamięć. “Unexpected token in JSON at position 47” - wszyscy wpatrywaliśmy się w to o 3 rano, próbując wypuścić release. Komunikaty są technicznie poprawne, ale często nieprzydatne: wymieniona pozycja rzadko jest tam, gdzie żyje prawdziwy błąd.

To przewodnik po błędach JSON, które naprawdę zobaczysz w praktyce - co znaczą i jak każdy szybko naprawić. Wszystkie przykłady testowane względem standardowego JSON.parse() używanego przez każdą przeglądarkę i Node.js.

1. “Unexpected token , in JSON”

Co to zwykle znaczy: końcowy przecinek.

{
 "name": "Alice",
 "role": "admin",
}

Przecinek po "admin" jest nieprawidłowy. JSON nie pozwala na końcowe przecinki - w przeciwieństwie do literałów obiektów JavaScript czy słowników Pythona.

Naprawa: usuń końcowy przecinek.

Uwaga: parser zwykle wskazuje linię po przecinku, a nie sam przecinek. Jeśli błąd mówi “linia 5”, najpierw patrz na linię 4.

2. “Unexpected end of JSON input”

Co to zwykle znaczy: plik jest obcięty. Brakuje zamykającego nawiasu.

{
 "users": [
 { "name": "Alice" },
 { "name": "Bob" }
 ]
← brakujący zamykający nawias klamrowy dla zewnętrznego obiektu

Naprawa: policz nawiasy. Większość edytorów pokazuje dopasowywanie nawiasów - ustaw kursor na otwierającym { i sprawdź, z czym się paruje.

Źródło to często nieudane pobieranie HTTP (połączenie zerwane przed przesłaniem całej odpowiedzi), niekompletny zapis crashującego procesu, uszkodzenie pliku. Sprawdź rozmiar pliku - jeśli spodziewałeś się 200 KB, a dostałeś 180 KB, plik jest obcięty. Wróć do źródła.

3. “Unexpected token } in JSON”

Co to zwykle znaczy: nadmiarowy zamykający nawias albo brakujący przecinek między kluczami.

{
 "name": "Alice" ← brakujący przecinek tutaj
 "role": "admin"
}

Naprawa: dodaj brakujący przecinek. Albo odwrotny przypadek:

{ "name": "Alice" } } ← nadmiarowy zamykający nawias

Naprawa: usuń nadmiarowy nawias.

4. “Unexpected token u in JSON”

Co to zwykle znaczy: dosłowny undefined jako wartość. undefined to wartość JavaScript - nie istnieje w JSON.

{ "role": undefined }

Naprawa: zastąp undefined przez null lub w ogóle pomiń klucz.

Źródło: ręczna edycja JSON lub niestandardowy serializer. JSON.stringify() sam w sobie obsługuje to poprawnie - pomija klucze z wartością undefined.

5. “Unexpected token < in JSON”

Co to zwykle znaczy: twój “JSON” to w rzeczywistości HTML. < to początek tagu.

<!DOCTYPE html>
<html>
 <head><title>500 Server Error</title>
 ...

Naprawa: sprawdź, co serwer naprawdę zwraca. To pewnie strona błędu w HTML zamiast oczekiwanej odpowiedzi JSON. Zrób console.log(response.text) przed parsowaniem - jeśli widzisz HTML, problem jest po stronie serwera, nie w parsowaniu JSON.

6. “Unexpected token ’ in JSON”

Co to zwykle znaczy: pojedyncze cudzysłowy zamiast podwójnych.

{ 'name': 'Alice' }

Stringi JSON muszą być w podwójnych cudzysłowach. Pojedyncze są nieprawidłowe, choć działają w JavaScript i Pythonie.

Naprawa: zastąp wszystkie pojedyncze cudzysłowy podwójnymi. Jeśli stringi zawierają dosłowne podwójne cudzysłowy, escape’uj je: \".

7. “Unexpected token n in JSON”

Co to zwykle znaczy: dosłowny znak nowej linii wewnątrz stringa.

{ "description": "hello
world" }

Stringi JSON nie mogą zawierać dosłownych znaków nowej linii. Muszą być escape’owane jako \n.

Naprawa:

{ "description": "hello\nworld" }

8. “Unexpected number in JSON”

Co to zwykle znaczy: liczba w nieprawidłowym formacie. Typowi winowajcy:

  • +5 (wiodący plus - niedozwolony)
  • 07 (wiodące zero przed liczbą całkowitą - niedozwolone)
  • 1. (kropka dziesiętna bez cyfry po niej)
  • .5 (wiodąca kropka bez zera)
  • Infinity, -Infinity, NaN (specjalne wartości JS - niedozwolone w JSON)

Naprawa: usuń wiodący +, zrzuć wiodące zera, dodaj brakujące zero (1. → 1.0, .5 → 0.5), zastąp Infinity/NaN przez null lub string wartowniczy.

9. “Duplicate key ’…’ in JSON”

Co to zwykle znaczy: obiekt ma ten sam klucz dwa razy.

{
 "name": "Alice",
 "name": "Bob"
}

Standardowe parsery to technicznie akceptują - po cichu biorą ostatnią wartość. Strict parsery to odrzucają i mają rację.

Naprawa: zdecyduj, która wartość jest poprawna, usuń drugą. Zawsze.

10. “Expected ’:’ after property name in JSON”

Co to zwykle znaczy: = zamiast :, albo brak dwukropka w ogóle.

{ "name" = "Alice" } ← źle
{ "name" "Alice" } ← źle

Naprawa: użyj dwukropka. Pamięć mięśniowa z YAML albo TOML potrafi tu nabroić.

11. Nieprawidłowy UTF-8 albo BOM

Plik zaczyna się od BOM (byte-order mark) albo zawiera nieprawidłowe bajty UTF-8. BOM (U+FEFF) to legacy’owy znacznik kodowania plików z Windows. Parsery JSON technicznie powinny go odrzucać, choć wiele toleruje go po cichu.

Naprawa: usuń BOM. Na macOS/Linux: tail -c +4 file.json > file-clean.json. Na Windows: zapisz plik jako “UTF-8 bez BOM” w edytorze. Źródło: Windows Notepad, produkty Microsoftu, starsze eksporty CMS.

12. Błędy “Circular structure” z JSON.stringify

To błąd serializacji, nie parsowania, ale pojawia się wystarczająco często:

const obj = { a: 1 }
obj.self = obj
JSON.stringify(obj) // TypeError: Converting circular structure to JSON

Naprawa: nie przekazuj struktury samoreferencyjnej do stringify. Spłaszcz dane przed serializacją albo użyj biblioteki jak flatted lub safe-stringify. Źródło: komponenty Reacta, węzły DOM, modele ORM z wstecznymi referencjami.

Workflow debugowania

Wpadłeś w błąd parsowania JSON - oto szybki porządek działania:

  1. Skopiuj problematyczny JSON do formatera
  2. Kliknij Formatuj - jeśli odrzuci, powie ci gdzie
  3. Patrz 2-3 linie powyżej raportowanej linii - prawdziwy błąd jest często wcześniej
  4. Sprawdź typowych winowajców - końcowy przecinek, brakujący przecinek, pojedynczy cudzysłów, niezamknięty string
  5. Jeśli JSON jest ogromny - wyszukiwanie binarne: usuń drugą połowę dokumentu i spróbuj ponownie. Jeśli parsuje - błąd jest w usuniętej połowie. Zawęź.
  6. Sprawdź źródło - czy API naprawdę zwróciło JSON, czy HTML / zwykły tekst?

Nawyki, które blokują błędy zanim się pojawią

Waliduj JSON przed commitowaniem plików konfiguracyjnych. Pre-commit hook z jq empty file.json łapie większość problemów.

Używaj lintera (ESLint, Prettier) który rozumie JSON i flaguje problemy przy zapisie.

Preferuj biblioteki serializacji zamiast ręcznego konstruowania stringów JSON. Ręczne konstruowanie to miejsce, skąd biorą się końcowe przecinki i nieescape’owane stringi. JSON.stringify robi to za ciebie poprawnie.

Trzymaj wartości typowane konsekwentnie. Nie przeplataj "1" (string) i 1 (liczba) dla tego samego pola w rekordach.

Wypróbuj formater

Większość błędów z tej listy znajdziesz w sekundy za pomocą naszego JSON Formatter. Wklej zepsuty JSON, kliknij Formatuj, przeczytaj komunikat błędu. Wszystko działa w przeglądarce - możesz debugować wrażliwe konfiguracje i odpowiedzi API bez wypuszczania ich z urządzenia.

JSON jest prosty z założenia, więc i błędy są proste - ale denerwujące, gdy jesteś pod presją. Dwie minuty w formaterze to zwykle wystarczy.