The Fix
Upgrade to version 0.16.0 or later.
Based on closed Kludex/starlette issue #1212 · PR/commit linked
Production note: Most teams hit this during upgrades or environment changes. Roll out with a canary and smoke critical endpoints (health, OpenAPI/docs) before 100%.
@@ -1,5 +1,6 @@
site_name: Starlette
site_description: The little ASGI library that shines.
+site_url: https://www.starlette.io
theme:
<url>
<loc>None</loc>
<lastmod>2021-06-23</lastmod>
<changefreq>daily</changefreq>
</url>
Re-run the minimal reproduction on your broken version, then apply the fix and re-run.
Option A — Upgrade to fixed release\nUpgrade to version 0.16.0 or later.\nWhen NOT to use: This fix should not be applied if the documentation structure changes significantly.\n\n
Why This Fix Works in Production
- Trigger: Starlette docs has dead links, broken sitemap and missing redirection for http://
- Mechanism: The mkdocs configuration was missing the site_url, causing broken links and sitemap issues
- Why the fix works: Sets the site_url in mkdocs.yml to fix broken links and sitemap issues related to issue #1212. (first fixed release: 0.16.0).
- If left unfixed, the same config can fail only in production (env differences), causing startup failures or partial feature outages.
Why This Breaks in Prod
- The mkdocs configuration was missing the site_url, causing broken links and sitemap issues
- Production symptom (often without a traceback): Starlette docs has dead links, broken sitemap and missing redirection for http://
Proof / Evidence
- GitHub issue: #1212
- Fix PR: https://github.com/kludex/starlette/pull/1215
- First fixed release: 0.16.0
- Reproduced locally: No (not executed)
- Last verified: 2026-02-09
- Confidence: 0.85
- Did this fix it?: Yes (upstream fix exists)
- Own content ratio: 0.76
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“Thanks for the report. The broken links should now be fixed and I have a PR open to fix this for the next release as…”
“^ This broke FastAPI docs that link to Starlette”
“@JayH5 Thanks for fixing it so quickly 😄”
Failure Signature (Search String)
- Starlette docs has dead links, broken sitemap and missing redirection for http://
- 2. Broken sitemap. `loc` is empty.
Copy-friendly signature
Failure Signature
-----------------
Starlette docs has dead links, broken sitemap and missing redirection for http://
2. Broken sitemap. `loc` is empty.
Error Message
Signature-only (no traceback captured)
Error Message
-------------
Starlette docs has dead links, broken sitemap and missing redirection for http://
2. Broken sitemap. `loc` is empty.
Minimal Reproduction
<url>
<loc>None</loc>
<lastmod>2021-06-23</lastmod>
<changefreq>daily</changefreq>
</url>
What Broke
Users encountered 404 errors and empty sitemap entries, impacting documentation accessibility.
Why It Broke
The mkdocs configuration was missing the site_url, causing broken links and sitemap issues
Fix Options (Details)
Option A — Upgrade to fixed release Safe default (recommended)
Upgrade to version 0.16.0 or later.
Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.
Fix reference: https://github.com/kludex/starlette/pull/1215
First fixed release: 0.16.0
Last verified: 2026-02-09. Validate in your environment.
When NOT to Use This Fix
- This fix should not be applied if the documentation structure changes significantly.
Verify Fix
Re-run the minimal reproduction on your broken version, then apply the fix and re-run.
Did This Fix Work in Your Case?
Quick signal helps us prioritize which fixes to verify and improve.
Prevention
- Capture the exact failing error string in logs and tests so you can reproduce via a minimal script.
- Pin production dependencies and upgrade only with a reproducible test that hits the failing path.
Version Compatibility Table
| Version | Status |
|---|---|
| 0.16.0 | Fixed |
Related Issues
No related fixes found.
Sources
We don’t republish the full GitHub discussion text. Use the links above for context.