flask Revisit SERVER_NAME's impact on routing and external

The Fix

Upgrade to version 3.1.0 or later.

Based on closed pallets/flask issue #5553 · 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%.

Jump to Verify Open PR/Commit

@@ -23,6 +23,9 @@ Unreleased
     secret keys that can still be used for unsigning. Extensions will need to
     add support. :issue:`5621`
+-   Fix how setting ``host_matching=True`` or ``subdomain_matching=False``
+    interacts with ``SERVER_NAME``. Setting ``SERVER_NAME`` no longer restricts
+    requests to only that domain. :issue:`5553`

repro.py

from flask import Flask, request, url_for

app = Flask(__name__)
app.config["SERVER_NAME"] = "example.com:5000"
app.url_map.default_subdomain = ""  # and patch out the `or None`

@app.get("/")
def index() -> str:
    return url_for("index", _external=True)

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

fix.md

Option A — Upgrade to fixed release\nUpgrade to version 3.1.0 or later.\nWhen NOT to use: Do not use this fix if you require SERVER_NAME to restrict routing to a specific domain.\n\nOption C — Workaround\nfor `SERVER_NAME` doing double-duty.  If we had two separate settings, then one should just be `EXTERNAL_HOST_URL` (or whatever you want to name it) and then you don't need `PREFERRED_URL_SCHEME`?\nWhen NOT to use: Do not use this fix if you require SERVER_NAME to restrict routing to a specific domain.\n\n

Why This Fix Works in Production

Trigger: That issue was closed by https://github.com/pallets/flask/pull/2635, which made a change regarding subdomain matching. However, IMO, it did not address the…
Mechanism: SERVER_NAME was improperly affecting routing and URL generation in Flask
Why the fix works: Fixes the interaction between SERVER_NAME and routing for subdomain and host matching. (first fixed release: 3.1.0).

Production impact:

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

SERVER_NAME was improperly affecting routing and URL generation in Flask
Production symptom (often without a traceback): That issue was closed by https://github.com/pallets/flask/pull/2635, which made a change regarding subdomain matching. However, IMO, it did not address the fundamental problem of `SERVER_NAME` impacting two disparate mechanisms in Flask.

Proof / Evidence

GitHub issue: #5553
Fix PR: https://github.com/pallets/flask/pull/5634
First fixed release: 3.1.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.60

Discussion

High-signal excerpts from the issue thread (symptoms, repros, edge-cases).

Jump to Sources Open on GitHub

“Thanks for the analysis and writeup, I was trying to do something similar and ran out of steam. I'll think about the exact path forward,…”

@davidism · 2024-11-06 · source

“I'm hesitant to deprecate/rename SERVER_NAME”

@davidism · 2024-11-02 · source

“SERVER_NAME does have a routing purpose in this case, without interfering: it allows determining the subdomain by comparing Host to SERVER_NAME”

@davidism · 2024-11-10 · source

“We should expose Werkzeug's trusted host checking, with a new ALLOWED_HOSTS = [] config to match Django's”

@davidism · 2024-08-15 · source

Failure Signature (Search String)

That issue was closed by https://github.com/pallets/flask/pull/2635, which made a change regarding subdomain matching. However, IMO, it did not address the fundamental problem of
In #2813, a minimal, complete, and verifiable example was requested and I have therefore prepared an [example gist that demonstrates the

Copy-friendly signature

signature.txt

Failure Signature
-----------------
That issue was closed by https://github.com/pallets/flask/pull/2635, which made a change regarding subdomain matching.  However, IMO, it did not address the fundamental problem of `SERVER_NAME` impacting two disparate mechanisms in Flask.
In #2813, a minimal, complete, and verifiable example was requested and I have therefore prepared an [example gist that demonstrates the problem](https://gist.github.com/rsyring/c50a500a5d35787ef45c1ff1e78d8898).

Error Message

Signature-only (no traceback captured)

error.txt

Error Message
-------------
That issue was closed by https://github.com/pallets/flask/pull/2635, which made a change regarding subdomain matching.  However, IMO, it did not address the fundamental problem of `SERVER_NAME` impacting two disparate mechanisms in Flask.
In #2813, a minimal, complete, and verifiable example was requested and I have therefore prepared an [example gist that demonstrates the problem](https://gist.github.com/rsyring/c50a500a5d35787ef45c1ff1e78d8898).

Minimal Reproduction

repro.py

from flask import Flask, request, url_for

app = Flask(__name__)
app.config["SERVER_NAME"] = "example.com:5000"
app.url_map.default_subdomain = ""  # and patch out the `or None`

@app.get("/")
def index() -> str:
    return url_for("index", _external=True)

What Broke

Incorrect URLs were generated in distributed tasks, causing routing issues.

Why It Broke

SERVER_NAME was improperly affecting routing and URL generation in Flask

Fix Options (Details)

Option A — Upgrade to fixed release Safe default (recommended)

Upgrade to version 3.1.0 or later.

When NOT to use: Do not use this fix if you require SERVER_NAME to restrict routing to a specific domain.

Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.

Option C — Workaround Temporary workaround

for `SERVER_NAME` doing double-duty. If we had two separate settings, then one should just be `EXTERNAL_HOST_URL` (or whatever you want to name it) and then you don't need `PREFERRED_URL_SCHEME`?

When NOT to use: Do not use this fix if you require SERVER_NAME to restrict routing to a specific domain.

Use only if you cannot change versions today. Treat this as a stopgap and remove once upgraded.

Fix reference: https://github.com/pallets/flask/pull/5634

First fixed release: 3.1.0

Last verified: 2026-02-09. Validate in your environment.

When NOT to Use This Fix

Do not use this fix if you require SERVER_NAME to restrict routing to a specific domain.

Verify Fix

verify

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
3.1.0	Fixed

Related Issues

No related fixes found.

Cluster: flask:configuration-error All hubs All clusters

Related clusters: Data consistency Other Duplicate processing

Sources

We don’t republish the full GitHub discussion text. Use the links above for context.

flask Revisit SERVER_NAME's impact on routing and external URL generation (Fix)