[초급] 판다스 KeyError, 이거 하나 모르면 반나절 그냥 날아감

이게 중요하다. 데이터 전처리의 90%는 에러와의 싸움이다.

데이터 좀 만져보겠다고 판다스(Pandas) 라이브러리 임포트하고 엑셀 파일 하나 불러왔을 거다. 그리고 특정 열(column)을 선택하는 순간, 어김없이 터지는 붉은색 에러 메시지. ‘KeyError’. 직장인 열에 아홉은 여기서 첫 번째 멘탈 붕괴를 경험한다. 나도 그랬다. 이건 당신의 코딩 실력 문제가 아님. 데이터 파이프라인 설계에서 가장 흔하게 발생하는 오염 데이터 처리의 첫 관문일 뿐이다.

Q. ‘KeyError’는 대체 왜 뜨는 건가?

A. 없는 열쇠로 잠긴 문을 열려고 하니까. 아주 간단한 원리다. 데이터 프레임이라는 큰 표 안에 존재하지도 않는 이름의 열을 달라고 요청했으니, 파이썬이 ‘그런 이름의 열은 없어!’라고 소리치는 거다.

# 이런 코드를 짰을 때 발생함
import pandas as pd
data = {‘이름’: [‘김철수’, ‘이영희’], ‘나이’: [30, 25]}
df = pd.DataFrame(data)
print(df[‘연봉’]) # ‘연봉’이라는 열은 존재하지 않음 -> KeyError 발생

이 에러를 피하는 방법은 단 하나다. 문을 열기 전에 내가 가진 열쇠 목록을 확인하는 것. 즉, 데이터 프-레임에 어떤 열들이 있는지 눈으로 직접 확인하는 습관을 들이면 된다.

# 해결책: df.columns로 전체 열 이름부터 확인한다.
print(df.columns)
# 출력 결과: Index([‘이름’, ‘나이’], dtype=’object’)

목록을 보고 내가 가진 열 이름으로만 데이터를 요청하면, 이 에러는 평생 볼 일 없다. 이게 기본이다.

초급 레벨에서 반드시 겪는 실수 3가지 (Feat. 해결책)

이론은 쉽다. 하지만 실전에서는 늘 예상치 못한 곳에서 발목이 잡힌다. 신입 시절, 나를 포함해 대부분이 겪었던 대표적인 삽질 3가지를 공유한다. 이것만 피해도 전처리 시간이 절반으로 줄어든다.

❌ 실수 1: 오타 혹은 공백 (Whitespace)

가장 흔하고, 가장 어이없게 시간을 뺏는 주범이다. ‘고객명 ‘ 처럼 열 이름 끝에 눈에 보이지 않는 공백이 숨어있거나, ‘Name’을 ‘name’으로 쓰는 대소문자 실수가 대표적이다. 코드는 1mm의 오차도 용납하지 않는다.

• 🚨 주의사항: 눈으로 아무리 봐도 똑같아 보인다는 게 함정이다. 복사-붙여넣기를 생활화해야 한다.
• ✅ 해결책: df.columns로 출력된 열 이름을 그대로 복사해서 코드에 붙여넣는 게 가장 확실하다. 만약 공백이 문제라면 df.columns = df.columns.str.strip() 코드로 모든 열 이름의 양옆 공백을 한 번에 제거하고 시작하는 것도 좋은 방법이다.

❌ 실수 2: 비어있는 값(NaN) 방치하고 연산 시도

KeyError 다음으로 마주하는 게 바로 비어있는 값, 즉 ‘결측치(NaN)’ 문제다. 예를 들어 ‘판매수량’ 열에 비어있는 칸이 하나라도 있으면, 그 열의 합계를 구하거나 평균을 계산할 때 결과가 이상하게 나오거나 에러가 터진다. 비어있는 값은 숫자가 아니기 때문이다.

• 🚨 주의사항: 데이터가 수백, 수천 줄 되면 비어있는 칸이 어디에 숨어있는지 찾기 어렵다. ‘분명 숫자로 채웠는데 왜 계산이 안 되지?’ 하며 시간을 낭비하게 된다.
• ✅ 해결책: 데이터를 불러오자마자 df.info() 명령어로 각 열의 데이터 개수와 비어있지 않은 값의 개수를 확인한다. 만약 비어있는 값이 발견되면, df['판매수량'].fillna(0) 처럼 특정 값(주로 0)으로 채우거나, df.dropna()로 해당 행 전체를 삭제하는 결단이 필요하다. 어떤 방법을 쓸지는 데이터의 목적에 따라 다르다.

❌ 실수 3: 데이터 타입(Dtype) 불일치

분명 숫자 ‘100’인데, 텍스트(‘100’)로 저장된 경우가 비일비재하다. 이런 ‘숫자인 척하는 문자’는 덧셈, 뺄셈 같은 산술 연산이 불가능하다. 반대로 텍스트인 줄 알았던 데이터가 숫자로 되어있어 문자열 관련 함수(예: .str.contains())를 쓸 때 에러가 나기도 한다.

• 🚨 주의사항: 엑셀에서 멀쩡해 보인다고 판다스에서도 같은 타입일 거라 착각하면 안 된다. 시스템은 데이터를 엄격하게 구분한다.
• ✅ 해결책: 위에서 언급한 df.info()나 df.dtypes로 각 열의 데이터 타입을 먼저 확인한다. 만약 ‘판매수량’ 열이 ‘object'(문자열) 타입으로 되어 있다면, df['판매수량'] = df['판매수량'].astype(int) 코드를 사용해 숫자(정수) 타입으로 강제 변환해줘야 한다.

데이터 전처리는 화려한 분석이 아니다. 위와 같은 지루하고 반복적인 오류를 잡는 ‘청소’ 작업에 가깝다. 이 청소 단계를 건너뛰면, 아무리 좋은 분석 모델을 가져와도 쓰레기 같은 결과만 나올 뿐이다. 기억하면 된다. 확인하고, 또 확인하는 것. 그게 시스템 안정성의 핵심이다.

PipeMaster-Lab 운영정책 및 제보 안내