메타데이터 작업 하나가 전체 카테고리 페이지를 500으로 만들었다

무엇이 터졌나

검색 결과에 나올 메타데이터(키워드·설명 등)를 확장하는 작업을 하던 중, 로컬과 프로덕션 양쪽에서 모든 분야별 카테고리 페이지가 500 오류를 내기 시작했다. 공고가 있는 페이지는 예외 없이 죽었다 — 즉 사실상 전 분야가 장애 상태였다.

원인을 어떻게 찾았나

겉으로 드러난 오류 메시지는 “본문이 이미 사용됐다”는, 스트리밍 응답이 중단됐을 때 나오는 2차 증상이었다. 진짜 원인을 찾으려면 그 아래를 더 파야 했다. 확인해 보니, 최근 커밋이 정렬 관련 함수를 새로 불러오면서 그 함수의 이름을 짧게 지었는데, 하필 그 페이지에는 창건 때부터 같은 이름의 지역 변수(쿼리 문자열을 담는 변수)가 이미 있었다. 새로 불러온 함수가 기존 변수에 가려지면서, 코드는 문자열을 함수인 것처럼 호출하려 했고 그 순간 오류가 났다. 지역 페이지들은 우연히 변수 이름이 달라서 무사했다.

왜 빌드에서 안 잡혔나

변수 이름이 겹쳐서 한쪽이 다른 쪽을 가리는 것은 문법적으로 완전히 합법적인 자바스크립트 코드다. 빌드 도구는 이것을 오류로 보지 않는다. 즉 “빌드가 통과했다”는 사실이 “배포해도 안전하다”는 것을 보장하지 않는 경우가 실제로 있다는 뜻이다.

무엇을 배웠나

변수 이름을 다른 자매 페이지와 통일하는 것으로 즉시 수정했지만, 더 중요한 교훈은 절차 쪽이었다. 페이지에 새로운 함수나 변수를 불러올 때는 그 페이지의 프론트매터에 이미 있는 이름과 충돌하는지 확인해야 한다. 그리고 이런 충돌은 빌드로 걸러지지 않으므로, 배포 전에 대표 라우트(카테고리 하나, 지역 하나, 홈 하나 정도)를 실제로 열어 확인하는 스모크 테스트가 필요하다. 이 교훈은 바로 다음 작업에서 실제로 효과를 봤다 — 새 컴포넌트를 두 페이지에 빠뜨린 것을 로컬 500 오류로 미리 잡아냈다.