2 min read · 394 words
FastAPI 기반 웹 애플리케이션에서 특정 API 호출 시 갑자기 FastAPI 404 에러가 발생해 당황하는 개발자들을 위한 글이다. 내가 모듈 정리 작업 중 실수로 지워버린 라우터를 아카이브에서 찾아내어 단숨에 복구한 트러블슈팅 과정을 공유한다.
문제 상황
운영 기록 기준, 나는 색인 탭에서 inspector card가 정상적으로 inspector state를 표시하도록 만들려고 시도했다. 하지만 화면에 정보가 나오지 않고 FastAPI 404 에러가 발생하며 완전히 망했다.
에러 증상
Chrome MCP visual sweep 과정에서 `/api/inspector/state` 엔드포인트가 404를 뱉는 것을 발견했다. 색인 카드에는 `Inspector 상태 로드 실패: inspector state HTTP 404`라는 명확한 에러 메시지가 표시되고 있었다. 내부 smoke-test 루프는 inspector를 타겟 목록에 포함하지 않고 있어서 사전에 이 문제를 잡지 못했다.
환경
FastAPI webapp 환경이었으며, 최근 sess140 모듈 정리(prune) 작업을 진행하면서 대상 파일들을 `_archive/sess140-prune/` 디렉토리로 이동시킨 상태였다.
시도했지만 실패한 방법
단순한 일시적 오류인가 싶어 webapp restart를 시도했다. 하지만 404 에러는 그대로 유지되었고 아무것도 해결되지 않았다.
FastAPI 404 에러 최종 해결
정확한 원인은 추가 확인이 필요하지만, 현재 확인된 원인은 다음과 같습니다. sess140 모듈 정리 과정에서 `webapp/routers/inspector.py`와 `webapp/seo/inspector.py` 두 모듈이 아카이브로 넘어가 버렸다. `_NullModule` stub 덕분에 router 자체는 살아남아 에러 없이 구동되었으나, 실제 연결된 routes가 0개여서 404가 발생한 것이었다. 나는 아카이브 폴더에서 이 두 파일을 원래 위치로 복원하여 문제를 잡았다.
안 쓰는 코드 정리하겠다고 칼춤을 추다가 멀쩡한 심장까지 도려낸 격이다. 역시 지울 때는 두 번 생각하고, 아카이브는 이래서 꼭 만들어 둬야 한다.
사용한 코드
내가 아카이브에서 파일을 복원할 때 사용한 쉘 명령어다.
# 아카이브에서 유실된 inspector 모듈 복원
cp _archive/sess140-prune/inspector.py webapp/routers/
cp _archive/sess140-prune/seo/inspector.py webapp/seo/검증 결과
복원 후 webapp restart를 실행하여 검증했다. `/api/inspector/state` 호출 시 HTTP 200 정상 응답을 확인했다. router.routes count가 6개 엔드포인트로 정상 복구되었으며, 색인 탭 카드도 정상적으로 표시된다. 현재 상태는 fixed이다.
같은 문제 겪는 분들에게
FastAPI에서 특정 엔드포인트가 갑자기 404를 뱉는다면, 최근에 진행한 코드 정리나 리팩토링 이력을 가장 먼저 의심해라. 특히 빈 라우터 껍데기만 남겨두는 stub 모듈이 동작 중인지 확인하는 것이 FastAPI 404 에러를 빠르게 해결하는 지름길이다.
Category Coverage Notice
This article follows our label-specific editorial criteria. Details: