설정 파일에서 값 하나만 바꿨습니다. 저장하고 실행했더니 서비스가 뜨지 않고 이런 메시지가 나옵니다.
SyntaxError: Unexpected token } in JSON at position 184
파일을 열어 봐도 어디가 잘못됐는지 보이지 않습니다. 중괄호와 따옴표가 빽빽해서 눈으로 훑는 것만으로는 찾기 어렵습니다.
JSON은 데이터를 텍스트로 적는 형식이고 규칙이 아주 적습니다. 그런데 그 적은 규칙을 하나라도 어기면 파일 전체가 통째로 거부됩니다. 부분적으로 읽어 주지 않습니다. 그래서 오타 하나가 서비스 전체를 멈춥니다. 실제로 자주 나오는 다섯 가지를 순서대로 봅시다.
먼저: JSON은 두 가지 모양뿐이다
{
"name": "김서연",
"age": 32,
"active": true,
"roles": ["admin", "editor"],
"team": { "id": 7, "label": "Growth" }
}
{ }객체: 이름표가 붙은 값들의 묶음."키": 값쌍을 쉼표로 나열합니다.[ ]배열: 순서대로 늘어놓은 값들의 목록.
값으로 올 수 있는 것은 문자열("..."), 숫자, true/false, null, 그리고 다시 객체나 배열입니다. 이게 전부입니다. 객체 안에 배열이 있고 그 안에 또 객체가 있는 식으로 깊어질 뿐, 규칙은 늘어나지 않습니다.
오류 1: 마지막 요소 뒤의 쉼표
가장 흔합니다.
{
"tags": ["work", "tools",]
}
"tools" 뒤의 쉼표가 문제입니다. JSON에서는 마지막 항목 뒤에 쉼표를 붙일 수 없습니다. JavaScript 코드에서는 허용되기 때문에 습관적으로 붙이게 되고, 항목을 지우다가 남는 경우도 많습니다. 오류 메시지가 ]나 }를 가리킨다면 대부분 그 바로 앞 쉼표를 보면 됩니다.
오류 2: 키에 따옴표가 없다
{ name: "kitfolio" }
name에 따옴표가 없습니다. JSON의 키는 반드시 큰따옴표로 감싸야 합니다. JavaScript 객체 리터럴에서는 생략할 수 있어 헷갈리는 부분입니다.
오류 3: 작은따옴표를 썼다
{ 'name': 'kitfolio' }
Python이나 JavaScript에서는 작은따옴표도 문자열이지만 JSON은 큰따옴표만 인정합니다. 다른 언어에서 데이터를 복사해 왔을 때 자주 발생합니다.
오류 4: 주석을 넣었다
{
// 운영 환경 설정
"env": "production"
}
JSON 표준에는 주석이 없습니다. tsconfig.json이나 .vscode/settings.json처럼 주석이 들어간 파일을 본 적이 있다면, 그건 JSON이 아니라 JSONC라는 확장 형식입니다. 특정 도구만 이해하며 일반 JSON 파서는 오류로 처리합니다.
오류 5: 괄호 짝이 안 맞는다
앞의 네 가지가 아니라면 대개 이것입니다. 중첩이 깊어지면 } 하나가 빠져도 눈으로는 찾기 어렵습니다.
이 다섯 가지를 순서대로 확인하는 것보다 빠른 방법이 있습니다. JSON 포매터에 파일 내용을 붙여 넣으면 오류 위치를 문자 단위로 짚어 줍니다. 앞의 position 184가 몇 번째 줄 어디인지 바로 보이므로, 원인을 찾는 시간이 대부분 사라집니다. 문제가 없다면 들여쓰기가 정리된 상태로 출력되어 구조도 함께 확인할 수 있습니다.
오류가 아닌데 값이 이상할 때
문법은 통과했는데 값이 이상하다면 다음 두 가지를 의심하세요.
아주 큰 숫자. JSON의 숫자는 대부분의 환경에서 배정밀도 부동소수점으로 읽힙니다. 9,007,199,254,740,992(2의 53제곱)를 넘는 정수 ID는 마지막 자릿수가 바뀔 수 있습니다. 그래서 긴 ID는 숫자가 아니라 문자열("1234567890123456789")로 주고받는 것이 관례입니다.
날짜. JSON에는 날짜 타입이 없습니다. 날짜는 문자열("2026-08-18T09:30:00Z")이거나 숫자(1755509400 같은 Unix 타임스탬프)로 들어옵니다. 후자를 읽으려면 타임스탬프 변환기로 사람이 읽는 날짜로 바꿔야 합니다. 초 단위와 밀리초 단위를 혼동하면 1970년이나 먼 미래가 나오니 자릿수를 확인하세요.
JSON을 쓰면 안 되는 경우
- 사람이 자주 손으로 고치는 설정 파일: 주석을 달 수 없어 "이 값이 왜 이런지"를 파일 안에 남길 수 없습니다. 이런 용도에는 YAML이나 TOML이 낫습니다.
- 아주 큰 데이터: 전체를 한 번에 읽어야 하는 구조라 수백 MB 파일에는 부적합합니다. 줄 단위로 처리하는 JSON Lines나 CSV를 씁니다.
- 정밀한 소수 계산이 필요한 값: 금액처럼 오차가 허용되지 않는 값은 숫자가 아니라 문자열로 주고받는 편이 안전합니다.
JSON을 다룰 때 실제로 필요한 지식은 이 정도입니다. 규칙이 적은 대신 예외를 봐주지 않는다는 성격만 기억하면, 오류 메시지를 보고 몇 초 만에 원인을 찾을 수 있습니다.