CSV 오류 가이드

최종 업데이트: 2026-03-30

시작하며

CSV를 DB에 넣거나 다른 시스템과 연동할 때 깨짐·중복 ID·보이지 않는 문자 등 때문에 오류가 나는 경우가 있습니다. 이 가이드에서는 대표적인 CSV 오류와 대처법을 설명하고, CSV 체커로 검사·수정하는 흐름도 안내합니다.

빠른 체크리스트: 가져오기가 실패하는 이유

CSV가 “겉보기엔 멀쩡한데” 가져오기가 실패할 때, 아래 항목을 위에서부터 빠르게 점검해 보세요. 대부분 몇 분 안에 원인을 찾을 수 있습니다.

• 구분자 불일치: 시스템은 쉼표를 기대하는데 탭/세미콜론을 쓰는 경우(또는 그 반대).
• 인코딩 불일치: 엑셀이 지역 인코딩(EUC-KR/CP949 등)으로 저장했는데 가져오기는 UTF-8을 기대하는 경우.
• BOM/헤더 문제: UTF-8 BOM, 헤더 중복, 헤더 행이 데이터 중간에 다시 들어간 경우.
• 열 개수 불일치: 특정 행만 쉼표가 부족/과다(따옴표 처리 깨짐, 텍스트 안의 쉼표 미이스케이프).
• 줄바꿈 혼재: CRLF/LF가 섞여 엄격한 파서에서 실패하는 경우.
• 보이지 않는 문자: 제로 너비 공백, NBSP, 탭, 제어 문자 등.
• 앞뒤 공백: “ID”와 “ID ”가 다른 값으로 취급되어 매칭/유니크 체크가 깨짐.
• 중복 ID: 유니크 키 열에 중복 값이 존재.
• 따옴표 필드: 따옴표가 닫히지 않거나 규칙이 일관되지 않아 파싱 오류가 나는 경우.
• 데이터 타입: 날짜/소수점이 로케일 형식으로 들어가 검증에서 실패하는 경우.

빠른 진단 흐름: 먼저 형식·기본 검사(인코딩/구분자/열/BOM) → 다음으로 단일 검사(중복/보이지 않는 문자/공백) 순으로 확인하세요. 글자가 깨지면 글자 깨짐 복원부터 실행하면 편합니다.

실무 사례: 10분 안에 원인 찾기

사례 A. 엑셀에서만 한글이 깨지는 파일

증상: 브라우저 미리보기는 정상인데 엑셀에서 열면 한글이 깨짐.

원인: 원본이 UTF-8(BOM 없음)이라 일부 엑셀 환경에서 로컬 인코딩으로 오인.

조치: 글자 깨짐 복원으로 UTF-8(BOM) 다운로드 후 재오픈.

사례 B. DB 업로드 시 유니크 키 에러

증상: 업로드 단계에서 “duplicate key” 오류 발생.

원인: ID 열에 중복 값 2건 + 일부 행의 앞뒤 공백으로 키가 혼재.

조치: 단일 검사에서 중복 ID 탐지 후 공백 트림 적용, 중복 행 정리 후 재업로드.

사례 C. 같은 고객인데 매칭 실패

증상: 눈으로는 같은 값인데 조인/검색에서 불일치.

원인: 제로너비 공백과 NBSP가 포함된 문자열.

조치: “보이지 않는 문자” 일괄 제거 후 비교 화면에서 결과 재검증.

1. 글자 깨짐(인코딩 불일치)

원인

CSV가 EUC-KR이나 CP949로 저장됐는데 UTF-8로 열거나, 그 반대인 경우 글자가 깨집니다. 엑셀에서 “CSV UTF-8”로 저장하지 않으면 많은 환경에서 EUC-KR(CP949)로 저장됩니다.

대처

• 원본 문자 코드를 올바르게 감지한 뒤 UTF-8(필요 시 BOM)으로 변환해 사용합니다.
• 사이트의 글자 깨짐 복원 도구는 브라우저 안에서 문자 코드를 자동 감지하고, UTF-8 BOM으로 다운로드합니다. 서버로 파일을 보내지 않습니다.

자세한 내용은 글자 깨짐·인코딩 문제를 참고하세요.

2. 중복 ID

원인

기본키나 유니크 키로 쓰는 열(ID·이메일 등)에 같은 값이 여러 행 있으면, DB 유일 제약 위반이나 병합 시 의도치 않은 덮어쓰기가 발생할 수 있습니다. 수동 입력이나 다른 시스템에서 가져올 때 중복이 섞이기 쉽습니다.

대처

• 가져오기 전에 키 열의 중복을 검사합니다.
• CSV 단일 검사에서는 “중복 ID”를 검사하고 해당 행을 목록으로 볼 수 있습니다. 수동 수정하거나, 중복을 허용하는 설계로 갈지는 업무에 맞춰 결정하면 됩니다.

중복 찾기·생각 정리는 중복 데이터 가이드에 있습니다.

3. 보이지 않는 문자·제어 문자

원인

다른 앱이나 웹에서 복사한 데이터에 제로 너비 공백·전각 공백·탭·줄바꿈 등 눈에 보이지 않는 문자가 포함될 수 있습니다. 검색·비교에서 “같아 보이는데 다르다”는 상황을 만듭니다.

대처

• 보이지 않는 문자를 검사해 제거하거나 정규화합니다.
• CSV 체커의 단일 검사에서는 “보이지 않는 문자”를 검사하고, 일괄 수정으로 제거할 수 있습니다. 앞뒤 공백 제거와 함께 쓰면 데이터가 더 일관됩니다.

4. 열 개수 불일치·빈 줄

원인

행마다 열 개수가 다르면(쉼표가 부족하거나 많음) 파서나 가져오기 도구가 오류를 낼 수 있습니다. 빈 줄이 섞이면 “헤더와 데이터가 어긋났다”고 잘못 인식되기도 합니다.

대처

CSV 형식·기본 검사에서 열 개수 불일치 행 수·빈 줄 유무를 확인할 수 있습니다. 해당 행을 찾은 뒤 원본을 수정하거나, 가져오기 시 “빈 줄 건너뛰기” 같은 옵션으로 처리하세요.

5. 헤더 중복

헤더 줄과 같은 내용의 행이 데이터 안에 있으면 열의 의미가 애매해집니다. 기본 검사로 “헤더 중복” 여부를 확인하고, 필요하면 해당 행을 삭제하거나 수정하세요.

CSV 체커로 확인하는 순서

1. 형식·기본 검사(inspect): CSV 하나를 올려 문자 코드·구분자·행 수·열 개수 불일치·빈 줄·헤더 중복을 확인합니다.
2. 단일 검사(check): 보이지 않는 문자·중복 ID·앞뒤 공백을 검사하고, 일괄 수정 후 다운로드합니다.
3. 글자가 깨진 파일은 먼저 글자 깨짐 복원(encoding-fix)으로 UTF-8 BOM으로 바꾼 뒤 위 검사를 진행하면 편합니다.

홈으로 · CSV 검사 시작