Python JSONDecodeError 원인 분석 및 해결 방법 완벽 가이드

많은 개발자가 프로그램의 데이터를 JSON 파일로 저장하고, JSON을 다루어야 하는 API를 활용합니다. 실제로 JSON과 파이썬의 딕셔너리(dictionary)를 활용할 사례는 어디서든 쉽게 찾아볼 수 있습니다.

다만 JSON 데이터를 다루다 보면 JSONDecodeError를 만나게 되는 경우가 종종 있습니다. 이 글에서는 JSONDecodeError가 발생하는 원인과 이를 해결하는 구체적인 방법을 예제와 함께 살펴보겠습니다.

Python JSONDecodeError란?

Python의 JSONDecodeError는 JSON 데이터의 형식에 문제가 있음을 나타내는 오류입니다. 예를 들어 중괄호({})가 누락되었거나, 값이 없는 키가 존재하거나, 콜론(:) 같은 필수 구문 요소가 빠져 있는 경우에 발생합니다.

JSONDecodeError를 근본적으로 해결하려면 JSON 파일을 직접 열어 문제가 된 부분을 확인해야 합니다. 앞으로 유사한 오류가 반복적으로 발생할 가능성이 있다면, try…except 블록으로 예외를 처리하도록 코드를 작성하는 것이 좋습니다.

오류가 발생하면 JSONDecodeError 키워드 뒤에 오류의 원인을 설명하는 간단한 메시지가 함께 출력되므로, 이 메시지를 먼저 확인하는 것이 문제 해결의 출발점입니다.

올바르게 작성된 JSON은 다음과 같은 형태를 가져야 합니다:

{
	"key": "value"
}

"value" 위치에는 리스트, 문자열, 숫자, 불린(Boolean), 또는 다른 JSON 객체처럼 유효한 JSON 값이면 무엇이든 올 수 있습니다.

예제 시나리오

회사에서 직원들에게 지급된 컴퓨터 정보를 JSON 객체 목록으로 저장하는 프로그램을 만든다고 가정해 보겠습니다. 각 JSON 객체는 아래와 같은 구조입니다:

[
	{
		"name": "Employee Name",
		"equip_id": "000"
	}
]

이 JSON 객체들은 equipment.json이라는 파일에 저장되며, 파일에는 다음과 같이 항목 하나만 들어 있습니다:

[
	{
		"name": "Laura Harper",
		"equip_id" "309"
	}
]

json 모듈을 사용하면 이 데이터를 프로그램으로 손쉽게 읽어올 수 있습니다:

import json

with open("equipment.json") as file:
	data = json.load(file)

print("Equipment data has been successfully retrieved.")

먼저 json 모듈을 임포트하여 JSON 파일을 읽을 준비를 합니다. 이후 open() 문으로 JSON 파일의 내용을 읽어들이고, with 문이 정상적으로 실행되면 장비 데이터가 성공적으로 조회되었음을 콘솔에 출력합니다.

이제 코드를 실행해 결과를 확인해 보겠습니다:

Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
  File "/usr/lib/python3.8/json/__init__.py", line 293, in load
	return loads(fp.read(),
  File "/usr/lib/python3.8/json/__init__.py", line 357, in loads
	return _default_decoder.decode(s)
  File "/usr/lib/python3.8/json/decoder.py", line 337, in decode
	obj, end = self.raw_decode(s, idx=_w(s, 0).end())
  File "/usr/lib/python3.8/json/decoder.py", line 353, in raw_decode
	obj, end = self.scan_once(s, idx)
json.decoder.JSONDecodeError: Expecting ':' delimiter: line 4 column 16 (char 47)

꽤 긴 오류 메시지가 출력되었습니다. 마지막 줄의 JSONDecodeError 뒤를 보면, Python이 오류의 원인을 친절하게 설명해 주는 것을 확인할 수 있습니다.

해결 방법

오류 메시지는 JSON 데이터에서 콜론(:)이 누락되었음을 알려주고 있습니다. 콜론은 네 번째 줄 16번째 열에 위치해야 한다고 명시되어 있네요. equipment.json 파일의 해당 줄을 살펴보면 JSON이 잘못 작성되었음을 바로 알 수 있습니다:

"equip_id" "309",

키와 값 사이에 콜론이 빠져 있습니다. 콜론을 추가하면 오류를 해결할 수 있습니다:

"equip_id": "309",

데이터 표현 방식의 문제를 수정했으니 프로그램을 다시 실행해 보겠습니다:

Equipment data has been successfully retrieved.

이번에는 코드가 오류 없이 성공적으로 실행됩니다.

try…except로 예외 처리하기

매번 파일 내용을 검수하기 어렵다면, try…except 핸들러를 사용해 이러한 문제를 미리 대비할 수도 있습니다. 이렇게 하면 나중에 다른 형식 오류가 발생하더라도 프로그램이 갑자기 중단되지 않습니다:

import json

try:
	with open("equipment.json") as file:
		data = json.load(file)

	print("Equipment data has been successfully retrieved.")
except json.decoder.JSONDecodeError:
	print("There was a problem accessing the equipment data.")

JSON 데이터에 오류가 있다면 프로그램은 다음 메시지를 출력합니다:

There was a problem accessing the equipment data.

반대로 JSON이 올바르다면, 프로그램은 데이터를 정상적으로 읽어온 후 콘솔에 다음 텍스트를 표시합니다:

Equipment data has been successfully retrieved.

마무리

Python의 JSONDecodeError는 JSON 객체의 형식에 문제가 있음을 의미합니다. 이 오류를 해결하는 핵심은 오류 메시지를 꼼꼼히 읽고, 안내된 위치(줄과 열)를 기준으로 JSON 데이터를 점검·수정하는 것입니다. 또한 try…except 블록을 활용하면 예기치 못한 형식 오류도 안전하게 처리할 수 있습니다.

Python 실력을 더욱 탄탄하게 쌓고 싶다면, 공식 문서와 온라인 학습 자료를 병행하며 JSON 처리, 파일 입출력, 예외 처리 같은 기초 주제를 차근차근 연습해 보는 것을 추천합니다. 작은 예제 프로젝트를 직접 만들어 보는 것이 가장 빠른 성장 방법입니다.