api-route-diagnostics

Diagnose and repair FastAPI routing failures using hypothesis-driven verification.

Updated Jul 6, 2026
One-click install
npx skills add https://github.com/Lucien-1127/strata-skill --skill api-route-diagnostics-lucien-1127
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-route-diagnostics
Source: https://github.com/Lucien-1127/strata-skill/tree/main/devops/api-route-diagnostics
Command: npx skills add https://github.com/Lucien-1127/strata-skill --skill api-route-diagnostics-lucien-1127

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When a FastAPI backend returns 404, 500, or timeout errors after deployment, developers often guess at fixes and break unrelated code. This Skill enforces a disciplined hypothesis-driven diagnostic workflow that locates the true root cause before any modification, applies minimal diffs, and verifies every endpoint afterward. ## Core Features & Use Cases - Hypothesis-Driven Diagnosis: Generates ranked root-cause hypotheses (missing routes, middleware ordering, schema mismatch, stale processes, dependency injection failures) with explicit verification methods before touching code. - Intensity Routing (L1/L2/L3): Controls reasoning depth per step — mechanical checks run fast, root-cause analysis gets full reasoning, preventing wasted tokens and premature conclusions. - Minimal-Diff Repair with Regression: Applies alias-route delegation patterns, backs up files before editing, then re-tests all registered endpoints including long-inference timeout scenarios. - Use Case: A frontend call to /api/chat returns 404 after a redeploy. The Skill confirms the process is alive, discovers the route is registered as /api/chat/ask, adds an alias route delegating to the existing handler, and verifies all endpoints return 200. ## Quick Start Diagnose why my FastAPI endpoint /api/chat returns 404 and fix it with minimal changes, then verify all other endpoints still work.

Frequently Asked Questions about api-route-diagnostics

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I diagnose a FastAPI 404 error on an existing endpoint?▼

First confirm the process is alive and the port is listening, then grep the source for the route decorator matching the requested path. If curl returns 404 but no matching decorator exists, the root cause is a missing or mismatched route path.

How to fix a FastAPI route mismatch without breaking the frontend?▼

Add an alias route that delegates to the existing handler rather than renaming the original endpoint. This preserves the frontend contract, avoids logic duplication, and keeps the diff minimal.

Why does my FastAPI code change not take effect after restart?▼

Common causes are stale processes still bound to the port or cached .pyc files. Check /proc/<PID>/cmdline against the on-disk path, kill the correct old process, and delete .pyc files before restarting.

Can middleware order cause FastAPI routes to fail?▼

Yes. If static mounts or middleware are registered before routes, they can shadow endpoints. Verify the registration order is CORS, then routes, then static mounts when diagnosing unexplained 404s.

What should I do when the FastAPI root cause cannot be confirmed?▼

Do not attempt speculative fixes. Output an undiagnosed status with the list of excluded hypotheses and their verification evidence, then escalate to deeper analysis of cross-module failures.