{"id":"8d06427abfec2385","repo":"pallets/flask","slug":"when-specifying-scheme-external-must-be-tru","errorCode":null,"errorMessage":"When specifying '_scheme', '_external' must be True.","messagePattern":"When specifying '_scheme', '_external' must be True\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/flask/app.py","lineNumber":1200,"sourceCode":"                url_adapter = self.create_url_adapter(None)\n\n            if url_adapter is None:\n                raise RuntimeError(\n                    \"Unable to build URLs outside an active request\"\n                    \" without 'SERVER_NAME' configured. Also configure\"\n                    \" 'APPLICATION_ROOT' and 'PREFERRED_URL_SCHEME' as\"\n                    \" needed.\"\n                )\n\n            # When outside a request, generate a URL with scheme and\n            # domain by default.\n            if _external is None:\n                _external = True\n\n        # It is an error to set _scheme when _external=False, in order\n        # to avoid accidental insecure URLs.\n        if _scheme is not None and not _external:\n            raise ValueError(\"When specifying '_scheme', '_external' must be True.\")\n\n        self.inject_url_defaults(endpoint, values)\n\n        try:\n            rv = url_adapter.build(  # type: ignore[union-attr]\n                endpoint,\n                values,\n                method=_method,\n                url_scheme=_scheme,\n                force_external=_external,\n            )\n        except BuildError as error:\n            values.update(\n                _anchor=_anchor, _method=_method, _scheme=_scheme, _external=_external\n            )\n            return self.handle_url_build_error(error, endpoint, values)\n\n        if _anchor is not None:","sourceCodeStart":1182,"sourceCodeEnd":1218,"githubUrl":"https://github.com/pallets/flask/blob/6a2f545bfd8ed31e19066a299296917e034aca58/src/flask/app.py#L1182-L1218","documentation":"Raised in `Flask.url_for()` (src/flask/app.py:1200) when `_scheme` is passed together with an explicit `_external=False`. A scheme (e.g. 'https') only appears in absolute URLs; a relative URL cannot carry one, and Flask rejects the combination explicitly to avoid silently dropping the scheme and producing accidentally insecure links.","triggerScenarios":"`url_for('endpoint', _scheme='https', _external=False)`. Inside a request, passing `_scheme` alone auto-sets `_external=True` (app.py:1173-1174), so the error only fires when `_external=False` is passed explicitly alongside `_scheme`.","commonSituations":"Copy-pasted url_for calls where someone added `_external=False` to 'fix' full URLs appearing in links while a global helper still passes `_scheme='https'`; wrapper functions that forward both kwargs with conflicting defaults; code written for older Flask versions where `_scheme` behavior differed (pre-2.2 required `_external=True` explicitly with `_scheme`).","solutions":["Remove `_external=False` — passing `_scheme` implies you want an absolute URL, and Flask will set `_external=True` for you.","If you actually want a relative URL, drop the `_scheme` argument instead.","To make all generated URLs https without per-call arguments, set `PREFERRED_URL_SCHEME = 'https'` in config (used outside requests) or fix your proxy headers (`X-Forwarded-Proto` with ProxyFix) so in-request URLs get the right scheme."],"exampleFix":"# before\nurl = url_for(\"login\", _scheme=\"https\", _external=False)\n\n# after\nurl = url_for(\"login\", _scheme=\"https\", _external=True)\n# or, for a relative URL:\nurl = url_for(\"login\")","handlingStrategy":"validation","validationCode":"kwargs = {'_scheme': 'https'}\nif '_scheme' in kwargs:\n    kwargs['_external'] = True\nurl = url_for('index', **kwargs)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pair `_scheme='https'` with `_external=True` in url_for calls","For app-wide HTTPS, set PREFERRED_URL_SCHEME='https' instead of passing _scheme per call","Wrap url_for in a small helper that enforces the pairing if you build external URLs in many places"],"tags":["flask","url-for","scheme","https"],"analyzedSha":"6a2f545bfd8ed31e19066a299296917e034aca58","analyzedAt":"2026-07-31T19:13:49.921Z","schemaVersion":2}