FastAPIで構築したWebアプリケーションで、特定のAPIを呼び出した際に突然404エラー（Not Found）が発生し、焦った経験はないでしょうか。今回は、モジュールの整理作業中に誤ってアーカイブに移動させてしまったルーターを特定し、無事に復旧させるまでのトラブルシューティングの流れを共有します。
発生した問題
インデックスタブ上の「inspector card」に「inspector state」が正しく表示されるように改修を行っていました。しかし、画面に情報が一切表示されず、バックエンドのFastAPI側で404エラーが発生してしまいました。
エラーの症状
ChromeのMCP visual sweepで確認したところ、`/api/inspector/state` エンドポイントが404を返していることが判明しました。UI上のインデックスカードには「Inspector状態のロード失敗: inspector state HTTP 404」と明確なエラーが表示されています。なお、内部のsmoke-testループの対象にこのinspectorが含まれていなかったため、事前の自動テストでは検知できませんでした。
環境
FastAPIで構築されたWebアプリケーション環境です。直前に「sess140」関連モジュールの整理（prune）作業を行っており、不要と思われるファイルを `_archive/sess140-prune/` ディレクトリに退避させたばかりでした。
試したこと（効果なし）
一時的なプロセスの不具合かと考え、ひとまずWebアプリケーションの再起動（webapp restart）を試みましたが、404エラーは解消されませんでした。
原因究明と解決方法
原因を調査したところ、モジュール整理の過程で `webapp/routers/inspector.py` と `webapp/seo/inspector.py` の2つの重要なモジュールまで誤ってアーカイブに移動させてしまっていたことが分かりました。厄介だったのは、`_NullModule` スタブが機能していたため、ルーター自体はエラーを出さずに起動してしまっていた点です。しかし、実体がないため紐づくルート（routes）数が0個になり、結果として404エラーが発生していました。
アーカイブフォルダからこれら2つのファイルを元のディレクトリに復元することで、無事に問題を解決できました。
不要コードを整理しようと張り切りすぎて、必要な心臓部まで削ぎ落としてしまった形です。やはりコードを削除・移動する際は細心の注意が必要ですね。退避用のアーカイブを作っておいて本当に助かりました。
復旧に使用したコマンド
アーカイブから紛失したモジュールを元の位置に復元するために実行したコマンドです。
# アーカイブから紛失したinspectorモジュールを復元
cp _archive/sess140-prune/inspector.py webapp/routers/
cp _archive/sess140-prune/seo/inspector.py webapp/seo/検証結果
ファイルを復元した後、Webアプリケーションを再起動して動作確認を行いました。`/api/inspector/state` へのリクエストに対してHTTP 200（OK）が返ってくることを確認。`router.routes` のカウントも6つのエンドポイントに正常に復旧し、インデックスタブのカードも正しく表示されるようになりました。ステータスは「解決（fixed）」です。
おわりに（同じ問題に直面している方へ）
FastAPIで特定のエンドポイントが突然404を返すようになった場合、直近で実施したコード整理やリファクタリングの履歴を真っ先に疑ってみてください。特に、中身が空のスタブモジュールが動いているせいでエラーが表面化せず、ルーティングだけが消えているケースは盲点になりやすいので、FastAPIの404エラー解決の参考になれば幸いです。
Category Coverage Notice
This article follows our label-specific editorial criteria. Details: