{"record":{"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":1203,"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":1185,"sourceCodeEnd":1221,"githubUrl":"https://github.com/pallets/flask/blob/3596b1ab61cea85edb8970e83ff61daa073facf8/src/flask/app.py#L1185-L1221","documentation":"Raised by Flask.url_for() when _scheme is set but _external is False. Forcing a scheme only makes sense for absolute (external) URLs; allowing scheme + internal would silently produce insecure/misleading URLs, so Flask rejects it explicitly.","triggerScenarios":"Calling url_for('endpoint', _scheme='https', _external=False) — scheme present but external explicitly disabled.","commonSituations":"Copy-paste of url_for args where _external was set to False for a relative link while keeping a _scheme; partial migration of http->https link logic.","solutions":["Set _external=True when using _scheme: url_for('endpoint', _scheme='https', _external=True).","Drop _scheme if you want a relative/internal URL.","Configure PREFERRED_URL_SCHEME in app config for default scheme instead of per-call _scheme."],"exampleFix":"// before\nurl_for('login', _scheme='https', _external=False)  # raises\n// after\nurl_for('login', _scheme='https', _external=True)","handlingStrategy":"validation","validationCode":"if scheme is not None and external is False:\n    raise ValueError('_external must be True when _scheme is set')\nurl_for('endpoint', _scheme=scheme, _external=external)","typeGuard":"def scheme_external_compatible(scheme, external) -> bool:\n    return scheme is None or external is True or external is None","tryCatchPattern":"try:\n    url = url_for('endpoint', _scheme=scheme, _external=external)\nexcept ValueError as e:\n    if '_external' in str(e):\n        external = True\n        url = url_for('endpoint', _scheme=scheme, _external=external)\n    raise","preventionTips":["Treat _scheme and _external as coupled: set both together.","Prefer PREFERRED_URL_SCHEME config for default scheme.","Wrap url_for helpers to enforce the invariant."],"tags":["url-building","value-error","configuration"],"backgroundTag":null,"analyzedSha":"3596b1ab61cea85edb8970e83ff61daa073facf8","analyzedAt":"2026-08-11T20:11:52.622Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}