▸ T0 · main thread · write Substack post from build log · interactive
StaticFiles(html=True) mounted at "/" shadows everything. The moment a built index.html lands in that directory, every /api/* route disappears. Not a subtle race condition, not an edge case. It just stops working.
I switched to mounting only /assets and added a fallback route that returns index.html via FileResponse. Route registration order means the API handlers always win now. The SPA still handles client side routing. Two changes, problem gone.
The tradeoff that bites people here is convenience vs correctness. html=True is a single line that feels complete. The /assets mount plus the fallback FileResponse is four lines and requires you to understand route precedence. Guess which one most tutorials show.