8. Python KeyError(딕셔너리에 없는 키 접근) 완벽 가이드

이 글에서는 Python 딕셔너리 사용 중 가장 흔히 마주치는 KeyError—존재하지 않는 키 접근 문제의 정의와 발생 원인, 대표 예제 및 해결 방법을 단계별로 살펴봅니다. 예제 코드와 실행 결과, 디버깅 팁을 통해 초보 개발자도 쉽게 이해하고 적용할 수 있도록 구성했습니다. 다음 챕터에서는 AttributeError: 없는 속성/메서드 호출 문제를 예고합니다.

1. KeyError란?

KeyError는 파이썬 딕셔너리에서 요청한 키(key)가 해당 맵핑(mapping)에 존재하지 않을 때 발생하는 내장 예외입니다. 파이썬 공식 문서에서는 “매핑(mapping)에서 키를 찾을 수 없으면 KeyError를 발생시킨다”라고 정의하고 있습니다. 이 예외는 런타임 중에 탐지되며, 에러 메시지에 문제가 된 키 이름을 포함해 발생 위치를 표시합니다.

2. 주요 발생 원인

• 오타로 인한 키 불일치: `'persn'`처럼 변수명 오타가 있으면 KeyError가 발생합니다.
• 키 선언 누락: 딕셔너리에 데이터를 추가하지 않고 조회만 시도할 때 발생합니다.
• 입력 데이터 검증 미흡: 사용자 입력이나 외부 API 응답이 예상한 키를 포함하지 않을 때입니다.
• DefaultDict 미사용: `collections.defaultdict` 대신 일반 `dict`를 사용해 기본값 처리 로직이 없을 때 발생합니다.
• 중첩 딕셔너리 접근 실수: `data['a']['b']` 접근 중 상위 키가 없으면 KeyError가 전파됩니다.

3. 실습 예제

아래 코드를 실행하면 KeyError가 발생하는 대표적인 상황을 확인할 수 있습니다.

# 예제: 딕셔너리에 없는 키 접근
user = {"name": "Alice", "age": 30}
print(user["email"])   # KeyError: 'email'

# 중첩 딕셔너리 오류 예시
profile = {"user": {"id": 1, "name": "Bob"}}
print(profile["user"]["email"])  # KeyError: 'email'

4. 실행 결과 및 설명

터미널에 아래와 같은 에러 메시지가 출력됩니다:

Traceback (most recent call last):
  File "example.py", line 2, in 
    print(user["email"])
KeyError: 'email'

Traceback (most recent call last):
  File "example.py", line 6, in 
    print(profile["user"]["email"])
KeyError: 'email'

메시지 끝에 표시된 키 이름('email')을 통해 어느 부분에서 문제가 발생했는지 바로 파악할 수 있습니다.

5. 해결 방법 & 디버깅 팁

1. in 연산자 사용: 접근 전 `if key in dict`로 존재 여부를 확인합니다.
2. get() 메서드 활용: `dict.get(key, default)`로 기본값을 지정해 예외를 방지합니다.
3. try-except 블록: `try: … except KeyError as e:`로 예외를 처리하고 로그를 남깁니다.
4. defaultdict 사용: `collections.defaultdict`로 기본값을 설정해 KeyError를 예방합니다.
5. 입력 값 검증: API 응답이나 사용자 입력 데이터를 미리 검증해 예상 키가 누락되지 않도록 합니다.

6. 정리 및 다음 단계

이번 챕터에서는 KeyError의 정의, 발생 원인, 예제 및 해결 방법을 살펴보았습니다. 키 존재 여부 확인과 기본값 처리 전략을 통해 KeyError를 효과적으로 예방하고 처리할 수 있습니다. 다음 챕터에서는 AttributeError: 없는 속성/메서드 호출 문제를 다룰 예정입니다.