Medusa.js 트러블슈팅과 디버깅의 자세

회사 쇼핑몰 개발에 Medusa.js를 활용하던 중, 상품 장바구니 추가 버튼을 누르면 calculate_amount를 찾을 수 없다는 에러 메시지가 발생했다. 원인을 찾기 위해 고군분투하다 결국 팀장님께 도움을 요청하게 되었다. 이 과정을 통해 기술적인 해결책을 넘어 에러를 대하는 개발자의 원초적인 접근법에 대해 큰 배움을 얻었다.

node_modules라는 블랙박스를 여는 용기

예전에 팀장님께서 “프레임워크를 사용하다 원인을 알 수 없는 에러를 마주치면 node_modules를 직접 까서 하나씩 접근해 보는 방법이 있다”고 말씀하신 적이 있었다. 당시에는 그 말이 크게 와닿지 않았으나, 이번에 팀장님이 에러에 접근하는 과정을 지켜보며 그 의미를 제대로 체감할 수 있었다.

팀장님은 에러 로그를 확인한 뒤, 망설임 없이 node_modules 내의 라이브러리 경로를 따라 들어갔다. 부끄럽게도, 라이브러리 내부 코드를 직접 수정하거나 분석할 수 있다는 사실을 처음으로 실감한 순간이었다. 팀장님은 코드의 흐름을 파악하며 의심 가는 지점에 console.log()를 찍어 데이터의 변화를 확인했는데, 라이브러리를 단순히 ‘가져다 쓰는 도구’가 아닌 ‘내가 분석하고 제어할 수 있는 코드’로 대하는 모습이 뭐랄까.. 이게 진짜 개발자구나 나는 아직 코더에서 벗어나려면 멀었구나를 느꼈다.

복잡한 구조 속에서 단서를 좁혀가는 과정

Medusa는 워크플로우(Workflow)와 스텝(Step) 단위로 로직이 구성되어 있고, 내부적으로 SQL 쿼리와 Join이 복잡하게 얽혀 있다. 이 때문에 특정 지점에서 값이 어긋나면 원인을 파악하기가 매우 까다로웠다.

한정된 시간 내에 모든 원인을 완벽히 규명하기는 어려워 디버깅을 잠정 중단해야 했지만, 팀장님이 로그를 통해 좁혀놓은 범위와 단서들은 나에게 결정적인 힌트가 되었다. 흐름을 타고 들어가며 원인을 좁혀가는 디버깅의 정석을 엿본 기분이었다.

결국 범인은 ‘대소문자’ 하나 (with Claude Code)

팀장님과 함께 찾아낸 단서들을 정리하여 클로드(Claude)에 전달했고, 마침내 근본적인 원인을 파악할 수 있었다. 원인은 정말이지 단순하게도 country_code의 대소문자 문제였다.

데이터베이스에 국가 코드를 넣을 때 대문자(KRW)로 저장해 두었는데, 정작 Medusa 내부 로직은 소문자를 기대하고 있었다. 이 사소한 불일치가 워크플로우를 꼬이게 만들었고, 결과적으로 calculate_amount를 참조해야 할 객체를 undefined로 만들어버린 것이었다.

디버깅은 결국 흐름을 쫓는 일이다

이번 트러블슈팅을 통해 두 가지 큰 깨달음을 얻었다.

첫째, 라이브러리 내부를 들여다보는 것을 두려워하지 말아야 한다는 점이다. node_modules는 성역이 아니라 분석 대상일 뿐, 그 안에 암호같은 코드들도 결국 하나씩 차근히 들여다보면 눈에 들어오게되어있다.

둘째, 데이터 정합성의 중요성이다. 대소문자 하나가 거대한 프레임워크의 워크플로우를 멈추게 할 수 있다는 사실에 소름이 좀 돋았다.

이번 경험은 정말 내 개발자 인생에 큰 도움이 되는 경험인것 같다.
팀장님의 디버깅 방식을 곁에서 배우며 한 단계 더 성장할 수 있었던 의미 있는 시간이였고, 역시 에러를 해결하는 과정이야말로 개발자에게 가장 큰 공부가 된다는 것을 느꼈다. 그렇지만 마주치고 싶지 않은것도 에러인것같다..