Виправляємо "Unexpected token" у JSON.parse: польовий довідник усіх причин

SyntaxError: Unexpected token X in JSON at position N — одна з найпоширеніших помилок у JavaScript і одна з найменш корисних: вона каже, де парсер здався, а не чому. Ось як її насправді виправити.

Крок 1: прочитайте номер позиції

JSON.parse рахує символи від початку рядка, починаючи з 0. Якщо ваш JSON прийшов зі змінної, перш ніж робити щось інше, виведіть у лог точний фрагмент навколо цієї позиції:

try {
  JSON.parse(raw);
} catch (e) {
  const match = e.message.match(/position (\d+)/);
  if (match) {
    const pos = Number(match[1]);
    console.log(raw.slice(Math.max(0, pos - 20), pos + 20));
  }
}

Цей єдиний фрагмент коду розв’язує більше таких помилок, ніж будь-які поради щодо синтаксису JSON, бо більшість помилок «unexpected token» — це насправді помилки «я не знаю, що насправді містить мій рядок»: хвостові пробіли після копіювання-вставлення, зайвий перенос рядка з шаблонного літерала або byte-order-mark (BOM) на самому початку (позиція 0, токен , невидимий у більшості редакторів).

7 причин, у порядку того, як часто вони насправді трапляються

1. Кома в кінці. {"a": 1, "b": 2,} — допустимо в об’єктних літералах JS, недопустимо в JSON. Кома перед } чи ] — найпоширеніша причина.
2. Одинарні лапки замість подвійних. {'a': 1} — це JS, а не JSON. JSON вимагає подвійних лапок і навколо ключів, і навколо рядкових значень, без винятків.
3. Ключі без лапок. {a: 1} — знову ж, валідний JS, невалідний JSON. Кожен ключ потребує лапок.
4. JS-значення, що не є валідним JSON. undefined, NaN, функція або коментар (// like this) — нічого з цього не існує у специфікації JSON, лише в JavaScript.
5. Подвійне кодування. Ви викликали JSON.stringify() двічі, або парсите рядок, який уже є об’єктом — перевірте через typeof raw === 'string' перед викликом .parse().
6. Порожній рядок або відповідь undefined. Якщо fetch мовчки впав чи повернув порожнє тіло, JSON.parse("") кидає Unexpected end of JSON input — інша, але споріднена помилка. Перевіряйте response.ok і логуйте сире тіло перед парсингом.
7. BOM або невидимі символи після копіювання-вставлення. Вставлення JSON із PDF, документа Word чи виводу термінала може принести BOM або нерозривний пробіл, що виглядає ідентично до звичайного символу.

Найшвидше виправлення: валідуйте, перш ніж дебажити

Читати сирі повідомлення про помилки символ за символом — повільно. Вставте точний рядок у форматер, який підсвічує невалідний символ безпосередньо, замість вгадування за номером позиції — це перетворює «десь біля символу 812» на «ось ця конкретна відсутня дужка, прямо тут». (Посилання нижче.)

Коли JSON справді валідний, але все одно не парситься

Якщо форматер підтверджує, що ваш JSON синтаксично коректний, а JSON.parse усе одно кидає помилку, то рядок, який ви передаєте, — не той, яким ви його вважаєте. Найпоширеніша причина: ви викликаєте .parse() на об’єкті Response, а не на його отриманому тілі.

// Wrong — parses "[object Response]", not the body
const data = JSON.parse(await fetch(url));

// Right
const data = await (await fetch(url)).json();
// or, if you need the raw text first:
const text = await (await fetch(url)).text();
const data = JSON.parse(text);

Короткий довідник

Симптом	Ймовірна причина
Unexpected token }	Кома перед закривною фігурною дужкою
Unexpected token '	Одинарні лапки замість подвійних
Unexpected token a (або будь-яка літера)	Ключ об’єкта без лапок
Unexpected end of JSON input	Порожній рядок, обірвана відповідь або незакрита дужка
Unexpected token  (позиція 0)	Byte-order-mark зі скопійованого або збереженого у Windows файлу

Нічого з цього не треба запам’ятовувати — виправлення завжди складається з тих самих трьох кроків: вивести в лог фрагмент навколо вказаної позиції, прогнати через форматер, виправити той один символ, на який він вкаже.