에러 메시지 읽는 법

앞 글에서는 디버깅할 때 문제를 작게 나누고, 코드가 실제로 어떤 값을 다루는지 확인하는 기본기를 살펴봤어요. 이번엔 그 과정에서 자주 마주치는 에러 메시지 읽는 법을 이야기해볼게요.

처음엔 빨간 글씨가 잔뜩 나오면 저도 좀 긴장했어요. 그런데 에러 메시지는 혼내는 문장이 아니라, 파이썬이 남긴 단서에 가깝습니다. 전부 한 번에 이해하려고 하지 않아도 괜찮아요. 어디서 시작해 어디를 확인할지만 알면, 원인을 찾기가 훨씬 수월해집니다.

에러 메시지는 어디부터 볼까?

파이썬 에러 메시지에서 오류 위치와 마지막 오류 이름을 확인하는 화면

파이썬은 오류가 나면 보통 Traceback으로 시작하는 내용을 보여줘요. 말 그대로 문제가 생기기까지 거쳐 온 경로입니다. 함수 호출이 여러 겹이면 관련된 파일과 줄이 차례로 나올 수 있어요.

처음부터 모든 줄을 읽느라 애쓰지 말고, 맨 아래쪽부터 살펴보세요. 마지막 줄에는 오류의 종류와 간단한 설명이 적혀 있는 경우가 많습니다.

Traceback (most recent call last):
  File "hello.py", line 2, in <module>
    print(message)
NameError: name 'message' is not defined

이 예에서는 마지막 줄이 NameError이고, message라는 이름을 찾지 못했다고 알려줍니다. 위쪽에는 문제가 난 파일과 줄 번호가 나와 있어요. hello.py의 2번째 줄에서 message를 사용했군요.

에러가 나면 저는 보통 이렇게 봅니다.

  1. 마지막 줄에서 오류 종류와 설명을 읽는다.
  2. 그 위에서 파일 이름과 줄 번호를 찾는다.
  3. 해당 줄과, 그 줄에 값을 넘긴 곳을 확인한다.

어? 줄 번호에 있는 코드가 멀쩡해 보이는데요? 그럴 땐 그 줄에서 사용한 값이 어디서 왔는지도 따라가 봐요. 원인이 바로 그 줄에 있다는 보장은 없거든요.

자주 만나는 오류, 뜻부터 잡기

NameError TypeError SyntaxError의 의미를 간단히 비교한 표

오류 이름은 처음 보면 낯설지만, 자주 보는 것부터 익히면 됩니다. 모든 오류 이름을 외울 필요는 없어요. 메시지를 보고 어떤 종류의 실수를 의심할지 감을 잡는 정도면 충분합니다.

오류 이름 쉽게 말하면 먼저 확인할 것
SyntaxError 코드 문법이 맞지 않음 괄호, 따옴표, 콜론
NameError 이름을 찾을 수 없음 변수 이름과 정의 여부
TypeError 값의 종류가 맞지 않음 연산이나 함수에 넣은 값
IndexError 리스트 범위를 벗어남 인덱스와 리스트 길이
KeyError 딕셔너리에 키가 없음 키 이름과 실제 데이터

이를테면 TypeError가 났다고 해볼게요. 숫자와 문자열을 더하려 했는지, 함수에 예상과 다른 값을 넘겼는지 확인해볼 수 있습니다. IndexError라면 리스트가 비어 있지는 않은지, 마지막 항목보다 큰 위치를 꺼내려 하지는 않았는지 살펴보면 되고요.

물론 오류 이름만으로 정답이 바로 나오진 않아요. 오류 이름은 방향을 알려주고, 설명과 코드가 원인을 좁혀줍니다.

줄 번호를 찾았는데 원인이 안 보일 때

잘못된 변수 이름에서 실제 값의 흐름을 따라 원인을 고치는 장면

파이썬이 가리킨 줄은 문제가 드러난 곳이지, 실수가 시작된 곳과 꼭 같지는 않습니다. 예를 들어 함수 안에서 잘못된 값을 받았거나, 변수를 만들 때 이름을 다르게 썼을 수 있어요.

user_name = "민지"
print(username)

눈으로 보면 user_name과 username이 비슷해서 그냥 지나치기 쉽죠. 하지만 파이썬 입장에선 서로 다른 이름입니다. username을 만든 적이 없으니 NameError가 나는 거예요.

이럴 때는 해당 줄만 반복해서 바라보기보다, 그 값을 어디서 만들었고 어떤 이름으로 전달했는지 위아래로 살펴보세요. 앞 글의 디버깅 습관처럼 확인용 출력으로 값을 찍어보는 것도 좋아요.

print(user_name)

저도 변수 이름 하나 빠뜨리고 한참 다른 코드를 의심한 적이 있어요. 솔직히 말하면, 그런 날은 커피 한 모금 마시고 다시 보면 어이없을 만큼 빨리 찾기도 합니다. 코드는 가끔 너무 침착하게 작은 오타를 숨겨요.

메시지가 모호하면 이렇게 추적해요

에러 메시지에서 재현 코드와 확인할 값을 차례로 좁혀 가는 흐름도

설명이 낯설거나 오류가 여러 줄에 걸쳐 있으면, 문제를 작게 만드는 게 도움이 됩니다. 입력값을 단순하게 바꿔보고, 관련 없는 코드를 잠깐 빼서 같은 오류가 다시 나는지 확인해보세요.

예를 들어 파일에서 데이터를 읽다가 문제가 생겼다면, 파일 전체를 한꺼번에 살피기 전에 문제가 난 줄에 어떤 값이 들어왔는지 출력해 볼 수 있어요. 함수 안에서 발생했다면 함수에 넘기는 값을 간단한 예시로 바꿔보는 식이죠.

그리고 검색이 필요하다면 에러 이름과 핵심 문구를 그대로 찾아보세요. 단, 검색 결과의 코드를 통째로 붙여넣기 전에 내 코드의 변수, 입력값, 줄 번호가 설명과 같은 상황인지 확인하는 게 중요합니다. 비슷한 오류라도 원인은 다를 수 있거든요.

제가 문제를 볼 때 자주 쓰는 순서는 이렇습니다.

  • 마지막 줄에서 오류 종류와 설명을 읽기
  • 표시된 파일과 줄 번호 확인하기
  • 그 줄에서 다루는 값과 이름 살펴보기
  • 입력과 코드를 줄여 같은 문제가 나는지 보기
  • 한 번에 한 가지씩 바꾸고 다시 실행하기

한꺼번에 여러 군데를 고치면 어떤 수정이 효과가 있었는지 헷갈릴 수 있어요. 작은 수정 뒤 다시 실행하는 습관이 원인을 또렷하게 보여줍니다.

에러를 읽는 습관은 다음 단계로 이어져요

에러 메시지를 읽을 때 중요한 건 모든 영어 표현을 외우는 일이 아닙니다. 오류 종류, 위치, 그 줄에 들어온 값을 차례로 확인하는 습관이 핵심이에요. 처음에는 검색을 곁들여도 괜찮고, 자주 만나는 오류는 쓰다 보면 자연스럽게 익숙해집니다.

다음 글에서는 여기서 한 걸음 더 나아가 볼게요. 코드가 예상한 조건을 만족하지 않을 때 우리가 직접 예외를 발생시키고, 상황에 맞는 예외를 만드는 방법을 다룹니다. 에러 메시지를 읽는 데 익숙해지면, 이제는 다른 사람이 이해하기 쉬운 메시지를 직접 남길 차례예요.

AIWD 소모임AI 자동화 오픈톡