CSV 헤더 공백이 만든 컬럼 선택 오류

2026년 6월 22일 | 개발 깨알 상식_Tips

---

CSV 헤더에 붙은 공백 하나는 로그에서 잘 보이지 않는데, 데이터프레임 안에서는 꽤 성가신 오류로 번진다. 값은 분명히 있는데 customer_id 컬럼을 고르면 없다고 나오고, 조인 키를 맞췄다고 생각했는데 결과 행 수가 갑자기 줄어든다. 파일을 열어 보면 사람 눈에는 같은 이름처럼 보이지만 실제 문자열은 customer_id, customer_id , customer_id처럼 조금씩 다르다.

나는 이런 문제를 한동안 값 전처리 쪽에서 찾았다. 결측값을 잘못 읽었나, dtype이 바뀌었나, 인코딩이 꼬였나를 먼저 봤다. 그런데 막상 원인은 헤더 줄의 보이지 않는 문자였다. 특히 여러 사람이 만든 CSV를 합치거나, 엑셀에서 저장한 파일과 시스템이 뽑은 파일을 같이 다룰 때 이 문제가 자주 튀어나온다.

헤더 공백 오류는 값 전처리보다 앞단에서 먼저 끊어야 재현과 보고가 쉬워진다.

겉으로는 같은 이름인데 선택은 실패한다

문제의 시작은 보통 아주 평범하다. pd.read_csv()로 파일을 읽고, 바로 필요한 컬럼을 고른다. 그런데 방금 눈으로 확인한 컬럼이 없다고 나온다. 이때 첫 번째로 볼 것은 데이터 값이 아니라 컬럼 이름 목록이다. 에러 메시지에 없는 컬럼명만 보고 다시 타이핑하기보다, 실제로 읽힌 헤더를 그대로 출력해 보는 편이 빠르다.

df = pd.read_csv(path)
print([repr(c) for c in df.columns])
# ["' customer_id'", "'amount '", "'\ufeffstatus'"]

여기서 repr()를 붙이는 이유는 앞뒤 공백과 BOM 같은 문자가 그냥 print(df.columns)에서는 흐릿하게 보이기 때문이다. 나는 작은 CSV 오류를 볼 때 컬럼 목록을 표 형태로 예쁘게 찍는 것보다, 이렇게 따옴표와 escape 문자가 드러나는 출력이 더 믿을 만하다고 느낀다.

skipinitialspace 하나로 끝나지 않는다

read_csv에는 skipinitialspace=True가 있다. 구분자 뒤의 공백을 건너뛰는 데 도움이 되지만, 모든 헤더 문제를 해결해 주는 만능 스위치로 생각하면 다시 헷갈린다. 파일 맨 앞의 BOM, 컬럼 이름 끝의 공백, non-breaking space, 중복 컬럼명은 별도 문제로 남을 수 있다.

그래서 나는 CSV를 읽은 직후에 헤더 정규화 단계를 값 정규화와 분리한다. 값에서 공백을 지우는 규칙과 컬럼 이름에서 공백을 지우는 규칙이 한 함수 안에 섞이면, 다음에 문제가 났을 때 “어느 단계에서 이름이 바뀌었는지”가 흐려진다. 헤더는 파일을 읽은 직후 한 번만 정리하고, 그 결과를 바로 검사하는 쪽이 낫다.

내가 먼저 보는 세 가지

첫째, 보이지 않는 문자를 본다. UTF-8 BOM(), 탭, non-breaking space는 복사한 헤더에서 생각보다 자주 섞인다. 둘째, 정규화 뒤 중복을 본다. name과 name 은 읽을 때는 다른 컬럼이지만, strip() 뒤에는 같은 컬럼이 된다. 셋째, 기대 스키마와의 차이를 본다. 필요한 컬럼이 모두 있는지, 추가 컬럼이 생겼는지, 이름이 바뀐 컬럼이 있는지를 파일 초반에서 확인한다.

여기서 중복 검사가 빠지면 더 위험하다. 정규화 자체는 성공한 것처럼 보이는데, 나중에 같은 이름의 컬럼 두 개가 생겨 하나가 조용히 덮이거나 선택 로직이 애매해질 수 있다. 작은 파일에서는 사람이 눈으로 잡지만, 배치에서는 이런 조용한 성공이 제일 늦게 발견된다.

추가로, 컬럼 이름을 사람이 읽는 라벨과 내부 키로 나누는 습관도 도움이 된다. 보고서에는 Customer ID처럼 보이게 두더라도, 처리 코드 안에서는 customer_id 같은 내부 이름으로 고정한다. 라벨 변경과 파이프라인 키 변경을 같은 사건으로 취급하면, 작은 표기 수정이 배치 실패로 이어지기 쉽다. 외부 파일을 받는 쪽에서 별칭표를 따로 두면, 팀원이 헤더명을 다듬어도 내부 검증 기준은 흔들리지 않는다.

정규화는 읽기 직후 한 번만

내가 자주 쓰는 형태는 대략 이렇다. 핵심은 멋진 helper를 만드는 것이 아니라, 헤더 정리와 실패 조건을 같은 위치에 두는 것이다. 이 함수는 컬럼 이름을 다듬은 뒤, 정규화 결과가 서로 충돌하면 바로 멈춘다.

def normalize_columns(columns):
    cleaned = (
        columns.astype("string")
        .str.replace("\ufeff", "", regex=False)
        .str.replace(" ", " ", regex=False)
        .str.strip()
    )
    if cleaned.duplicated().any():
        dupes = cleaned[cleaned.duplicated()].tolist()
        raise ValueError(f"duplicate columns after normalization: {dupes}")
    return cleaned

df = pd.read_csv(path)
df.columns = normalize_columns(df.columns)

expected = {"customer_id", "amount", "status"}
missing = expected - set(df.columns)
if missing:
    raise KeyError(f"missing required columns: {sorted(missing)}")

이 정도만 있어도 실패 위치가 꽤 선명해진다. 파일을 읽는 순간 실패했는지, 헤더 정규화 뒤 중복이 생겼는지, 아니면 기대 스키마와 실제 파일이 달랐는지를 나눌 수 있다. 나중에 보고할 때도 “컬럼이 없다”보다 “헤더 끝 공백 제거 후 name이 중복됐다”가 훨씬 덜 애매하다.

테스트 샘플에는 이상한 헤더를 그대로 남긴다

이 문제를 한 번 겪고 나면 테스트 파일을 너무 깨끗하게 만들고 싶은 마음이 든다. 하지만 그러면 같은 실수가 다시 들어왔을 때 방어 코드가 실제로 작동하는지 확인하기 어렵다. 나는 정상 헤더 하나, 앞뒤 공백이 붙은 헤더 하나, BOM이 섞인 헤더 하나를 작은 샘플로 남기는 편이 좋았다.

중요한 건 모든 CSV를 처음부터 완벽하게 정리하는 태도가 아니다. 파일을 읽은 직후 헤더를 한 번 의심하는 위치를 만드는 것이다. 그 위치가 있으면 값 전처리, 조인, 집계가 실패했을 때 원인을 아래쪽 로직에서만 뒤지지 않게 된다. 작은 공백 하나가 만든 오류라도, 헤더 단계에서 끊어 두면 다음 디버깅은 훨씬 짧아진다.