모델은 정상 작동, 응답은 500 오류? 실무에서 놓치기 쉬운 엑셀 파싱 이슈

 

 

 

문제 상황

최근에 한 프로젝트에서 사용자 업로드 파일을 api모델에서 파싱하여 처리하는 도중 500 (Internal Server Error)가 발생했다.

특이한 점은, 템플릿 파일을 그대로 업로드하면 문제 없고, 사용자가 수정한 파일만 오류가 발생했다는 점. 이 문제상황을 해결하기 위한 내용들을 정리하여 포스팅 하였다.

 

 

 

목차

---

 

 

 

 

 

500 오류 원인 분석

처음엔 프론트엔드 JSON 전송 문제를 의심했지만, 확인 결과 문제가 없었다.
서버 로그에도 오류가 남지 않아 의문이 깊어졌는데...

결정적 단서는 "수정한 엑셀 파일"의 저장 프로그램이었다.

[화면 진입]
    ↓
[템플릿 다운로드] ─────┐
                      ↓
       [MS 엑셀로 수정] → ✅ 예측 결과 출력
                      ↓
     [한셀로 수정] → ❌ 500 오류 발생

 

 

 

 

 

원인은 한셀?

문제가 발생한 파일은 **한셀(한컴오피스)**로 열어서 저장된 파일이었다.

한셀은 .xlsx 파일을 저장하더라도 내부 구조가 엑셀과 다르게 저장되기 때문에,
서버에서 파싱 시 예외가 발생할 수 있다고 한다...

예: 셀 타입 변경, 시트 이름 누락, XML 구조 불일치 등

 

 

 

 

해결 전략

✅ 사용자 가이드 활용(시점별 정리)

시점	안내효과	이유
✅ 다운로드 시	최고	이 시점이 사용자의 편집 도구에 영향을 줄 수 있음
✅ 업로드 시	보조	놓친 사용자에게 한 번 더 경고 가능
❌ 오류 발생 후	최악	사용자 입장에서 "왜 안 되냐"만 남음

 

 

모바일 UX까지 고려한 안내법

• title 툴팁은 모바일에서 잘 안 보임
• 눈에 띄는 <p> 텍스트나 alert() 방식 추천
• 아이콘과 텍스트 조합도 가독성 좋음

<p class="file-guide">
  ⚠️ 이 파일은 반드시 <strong>MS Excel</strong>에서 수정 후 업로드해주세요.  
  한셀로 저장 시 오류가 발생할 수 있습니다.
</p>

 

 

 

 

 

결론 및 개선 포인트 요약

• 엑셀 .xlsx라고 모두 같은 파일이 아니다 (한셀은 다르다!)
• 사용자 UX를 고려한 안내는 에러보다 훨씬 적은 비용으로 문제를 예방할 수 있다
• 모바일 환경에서는 툴팁보다 눈에 띄는 직접 안내가 효과적이다