FastAPIで何も変えてないのに認証が通らなくなる理由 ── Depends が静かに壊れて 401 / 403 になるケース
はじめに:何が起きたか
Depends を yield に変えたあと、
422 Unprocessable Entity や 401 / 403 が突然返るようになることがある。
トークンは送っている。
Authorization ヘッダーも付いている。
/token は普通に通る。
それなのに、
Depends を使ったエンドポイントだけが
401 / 403 を返す。
この事故が厄介な理由
Depends 周りの事故が厄介なのは、
壊れていても静かなところだ。
例外は投げられているかもしれない。
関数は呼ばれていないかもしれない。
戻り値はどこにも渡っていないかもしれない。
それでも FastAPI 自体は落ちない。
結果として、
- 認証が壊れているのか
- トークンが無効なのか
- 実装が間違っているのか
切り分けが一気に難しくなる。
Depends は「書いたら動く」わけではない
Depends は、
書いた時点で何かをしてくれる仕組みではない。
- 呼ばれて
- 実行されて
- 戻り値が使われて
初めて意味を持つ。
そのどこかが欠けていても、
構文としては正しいまま動いてしまう。
この「静かさ」が、
事故に気づきにくくする。
ありがちな壊れ方
Depends が絡む事故には、
だいたい決まったパターンがある。
- Depends の戻り値を、どこでも使っていない
- Depends 内で例外を投げているが、意図した形で伝播していない
- Depends 自体が呼ばれていない
- Depends を Depends で包みすぎて、流れが見えなくなっている
どれも、
書いている最中は「それっぽく」見える。
切り分けは「呼ばれているか」から
この事故で最初にやるべきことは、
設定を疑うことでも、コードを書き直すことでもない。
- Depends は本当に実行されているか
- その戻り値は、どこに渡っているか
- 例外は、どこで止まっているか
順番に確認すれば、
FastAPI 自体が原因でないことは、すぐ分かる。
よくある勘違い
- Depends を書けば、認証は動くと思っていた
- 401 / 403 が返る=認証が正しく機能していると思っていた
- 型が合っていれば問題ないと思っていた
Depends は便利だが、
状態を保証してくれる仕組みではない。
まとめ
401 / 403 が返るからといって、
認証が正しく動いているとは限らない。
Depends は、
正しく呼ばれているかどうかがすべてだ。
帰り際の一言
依存しているつもりでも、
依存関係は一方通行なことがある。
※同様の認証トラブルの原因切り分けを行っています。記事末尾に相談窓口を記載しています。
🛠️ FastAPI インシデント分析シリーズ
「401 / JWT / Dockerでだけ壊れる」など、原因切り分けが難しいケースをパターン別に公開しています。
🔐 認証・JWTトラブル
/tokenは通るのに /me が401になる理由
[https://zenn.dev/fastapier/articles/0022f125547300]
環境変数は設定したのに SECRET_KEY が None になる理由
[https://zenn.dev/fastapier/articles/e93b522cc0acb3]
401 / 403 を取り違えると、原因が見えなくなる
[https://zenn.dev/fastapier/articles/41f9e2e10e7c19]
🐳 Docker・本番環境トラブル
ローカルでは動くのに本番だけ落ちる理由
[https://zenn.dev/fastapier/articles/c90e5199e0bafc]
Dockerにしたら logging が出なくなった理由
[https://zenn.dev/fastapier/articles/cd530c54b6e47c]
🏗️ 設計・運用トラブル
main.pyが1000行を超えたときに起きる崩壊の理由
[https://zenn.dev/fastapier/articles/a2a9a5209dedac]
🩺 FastAPI事故 相談窓口(原因特定・構造分析)
FastAPI / JWT / Docker 周りの認証トラブルで、
/token は通るのに /me が 401 になる
本番環境でのみ InvalidSignatureError が発生する
Docker化後にだけ認証が落ちる
など、「原因の層が見えにくい事故」の切り分けと修正方針の整理を行っています。
3時間以上調査しても原因が特定できない場合、
それはコードではなく「構造」に問題がある可能性が高いです。
📩 ご相談方法
GitHubプロフィールに記載のメールアドレスまでご連絡ください。
[https://github.com/hiro-kuroe]
メール本文に、以下3点だけご記載ください(短文でOKです):
① 症状
(例:/me が 401 / 本番だけ署名エラー / Docker化後に認証失敗)
② 環境
(例:ローカルはOK、本番のみNG / Docker使用 / Gunicorn使用 など)
③ 直前に変更した点
(例:SECRET_KEY変更 / .env追加 / 依存パッケージ更新 など)
※まずは分析フェーズ(原因特定と構造整理)から進めます。
修正作業は、原因が明確になった後にご提案します。
Discussion