Sửa lỗi "Unexpected token" trong JSON.parse: cẩm nang cho mọi nguyên nhân

SyntaxError: Unexpected token X in JSON at position N là một trong những lỗi phổ biến nhất trong JavaScript, và cũng là một trong những lỗi ít hữu ích nhất — nó chỉ cho bạn biết vị trí mà trình phân tích cú pháp bỏ cuộc, chứ không nói tại sao. Đây là cách khắc phục thực sự.

Bước 1: đọc con số vị trí

JSON.parse đếm ký tự từ đầu chuỗi, bắt đầu từ 0. Nếu JSON của bạn đến từ một biến, hãy in ra đúng đoạn ký tự quanh vị trí đó trước khi làm gì khác:

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));
  }
}

Chỉ riêng đoạn mã này đã giải quyết được nhiều lỗi loại này hơn bất kỳ lời khuyên nào về cú pháp JSON, bởi vì phần lớn lỗi “unexpected token” thực chất là lỗi “tôi không biết chuỗi của mình thực sự chứa gì” — khoảng trắng thừa từ thao tác copy-paste, một ký tự xuống dòng thừa từ template literal, hoặc dấu byte-order-mark (BOM) ngay đầu chuỗi (vị trí 0, token , vô hình trong hầu hết trình soạn thảo).

7 nguyên nhân, xếp theo tần suất gặp phải trên thực tế

Dấu phẩy thừa ở cuối. {"a": 1, "b": 2,} — hợp lệ trong object literal của JS, nhưng không hợp lệ trong JSON. Dấu phẩy trước } hoặc ] là nguyên nhân phổ biến nhất.
Dùng dấu nháy đơn thay vì nháy kép. {'a': 1} là JS, không phải JSON. JSON yêu cầu dấu nháy kép cho cả khóa lẫn giá trị chuỗi, không có ngoại lệ.
Khóa không có dấu nháy. {a: 1} — cũng vậy, hợp lệ trong JS nhưng không hợp lệ trong JSON. Mọi khóa đều cần có dấu nháy.
Một giá trị JS không phải JSON hợp lệ. undefined, NaN, một hàm, hoặc một chú thích (// như thế này) — không cái nào trong số này tồn tại trong đặc tả JSON, chúng chỉ tồn tại trong JavaScript.
Mã hóa hai lần. Bạn đã gọi JSON.stringify() hai lần, hoặc bạn đang parse một chuỗi vốn đã là object rồi — hãy kiểm tra bằng typeof raw === 'string' trước khi gọi .parse().
Phản hồi rỗng hoặc undefined. Nếu một lệnh fetch thất bại âm thầm hoặc trả về nội dung rỗng, JSON.parse("") sẽ ném ra lỗi Unexpected end of JSON input, một lỗi khác nhưng có liên quan — hãy kiểm tra response.ok và in ra nội dung thô trước khi parse.
BOM hoặc ký tự vô hình từ copy-paste. Dán JSON từ một file PDF, tài liệu Word, hoặc kết quả từ terminal có thể mang theo dấu BOM hoặc khoảng trắng không ngắt (non-breaking space) trông giống hệt ký tự bình thường.

Cách sửa nhanh nhất: kiểm tra trước khi debug

Đọc thông báo lỗi thô từng ký tự một rất mất thời gian. Thay vì đoán mò từ con số vị trí, hãy dán chính xác chuỗi đó vào một công cụ định dạng có khả năng làm nổi bật trực tiếp ký tự không hợp lệ — nó biến “đâu đó gần ký tự thứ 812” thành “chính xác dấu ngoặc bị thiếu này, ngay đây.” (Liên kết ở dưới.)

Khi JSON thực sự hợp lệ nhưng vẫn báo lỗi

Nếu công cụ định dạng xác nhận JSON của bạn đúng cú pháp mà JSON.parse vẫn báo lỗi, thì chuỗi bạn đang truyền vào không phải là chuỗi bạn nghĩ. Lý do phổ biến nhất: bạn đang gọi .parse() trên một đối tượng Response thay vì phần nội dung (body) đã được xử lý xong.

// Sai — parse "[object Response]", không phải nội dung thực
const data = JSON.parse(await fetch(url));

// Đúng
const data = await (await fetch(url)).json();
// hoặc, nếu bạn cần văn bản thô trước:
const text = await (await fetch(url)).text();
const data = JSON.parse(text);

Bảng tra nhanh

Triệu chứng	Nguyên nhân khả dĩ
`Unexpected token }`	Dấu phẩy thừa trước dấu ngoặc đóng
`Unexpected token '`	Dùng dấu nháy đơn thay vì nháy kép
`Unexpected token a` (hoặc bất kỳ chữ cái nào)	Khóa object không có dấu nháy
`Unexpected end of JSON input`	Chuỗi rỗng, phản hồi bị cắt cụt, hoặc thiếu dấu ngoặc đóng
`Unexpected token` (vị trí 0)	Byte-order-mark từ file được copy-paste hoặc lưu trên Windows

Không có mục nào trong số này cần phải học thuộc lòng — cách sửa luôn theo cùng ba bước: in ra đoạn ký tự quanh vị trí được báo lỗi, chạy qua một công cụ định dạng, và sửa đúng ký tự mà nó chỉ ra.