V8 Node v24.15.0, V8 13.6.233.17에서 파서를 실행해 확인했습니다.
Bad control character in string literal in JSON at position N (line L column C)
문서 안의 어떤 문자열에 날 제어 문자가 들어 있습니다. 대개는 진짜 줄바꿈이고, 가끔은 탭입니다. JSON 문자열은 U+0020 미만의 문자를 이스케이프 없이 담을 수 없습니다. 줄바꿈은 \n으로, 탭은 \t로 써야 합니다. 위치는 문제가 된 그 문자를 가리킵니다.
JSON을 붙여넣고 어디서 깨지는지 정확히 확인하기
입력
붙여 넣은 것은 여러분의 브라우저를 떠나지 않습니다. connect-src 허용 목록 덕분에 이는 약속이 아니라 브라우저가 강제하는 보장입니다. 직접 확인하기
실제 원인
어느 쪽이 답인 경우가 많은지, 그 순서대로 정리했습니다.
-
01 여러 줄 텍스트를 문자열에 그대로 붙여 넣음
SQL, HTML, 로그 발췌, 또는 진짜 줄바꿈이 든 오류 메시지 같은 것들입니다. 파서 입장에서는 그 줄바꿈이 문자열의 끝입니다.
깨지는 예
{ "query": "SELECT * FROM users" }되는 예
{ "query": "SELECT *\nFROM users" } -
02 문자열 이어붙이기로 만든 JSON
거의 모든 사례의 근본 원인입니다. 손으로 조립한 JSON은 끼워 넣은 값을 이스케이프하지 않습니다. 대신 객체를 직렬화하면 이 문제는 애초에 생길 수 없습니다.
깨지는 예
const body = '{"note": "' + note + '"}';되는 예
const body = JSON.stringify({ note }); -
03 복사·붙여넣기로 딸려 온 탭
탭은 눈에 보이지 않고, 스프레드시트나 터미널에서 복사할 때 문자열 안으로 쉽게 들어옵니다. \t로 이스케이프하거나, 문서를 만들기 전에 제거하세요.
-
04 값 안에 들어간 윈도우 줄바꿈
캐리지 리턴(U+000D)도 제어 문자입니다. 윈도우 파일에서 읽어 문자열에 넣은 텍스트는 \n과 함께 \r도 끌고 옵니다.
다른 런타임에서의 같은 실수
밑바탕의 문제는 똑같고, 다른 건 문구뿐입니다. 동료가 이 중 하나를 들고 왔다면, 그 사람이 보고 있는 건 여러분이 보는 것과 같습니다.
| Python | Invalid control character at: line 1 column 8 (char 7) |
|---|---|
| Java (Jackson) | Illegal unquoted character ((CTRL-CHAR, code 10)): has to be escaped using backslash to be included in string value |
자주 묻는 질문
- 어떤 문자를 이스케이프해야 하나요?
- U+0000부터 U+001F까지 전부와, 큰따옴표, 백슬래시입니다. JSON은 백스페이스, 폼 피드, 줄바꿈, 캐리지 리턴, 탭에 짧은 이스케이프를 정의합니다. 그 범위의 나머지는 \u0000처럼 \u 형태가 필요합니다.
- 파서가 그걸 받아들이게 할 수 있나요?
- Jackson에는 ALLOW_UNESCAPED_CONTROL_CHARS가 있고 비슷한 스위치를 가진 파서도 있습니다. 하지만 그건 문제를 고치는 게 아니라 감추는 것이고, 문서는 다른 모든 소비자에게 여전히 유효하지 않습니다. JSON을 만들어 내는 지점에서 이스케이프하세요.