From ab2a92e0a2330be6cb2c14d80404eea62ddb28d6 Mon Sep 17 00:00:00 2001
From: Yurii Motov <yurii.motov.monte@gmail.com>
Date: Tue, 25 Nov 2025 20:47:48 +0100
Subject: [PATCH] Handle mistakes when wrong value is passed to `scope`

---
 fastapi/param_functions.py              | 18 ++++++++++++++
 tests/test_security_scopes_parameter.py | 32 ++++++++++++++++++++++++-
 2 files changed, 49 insertions(+), 1 deletion(-)

diff --git a/fastapi/param_functions.py b/fastapi/param_functions.py
index eee7542fa..eae6f0ae3 100644
--- a/fastapi/param_functions.py
+++ b/fastapi/param_functions.py
@@ -2307,6 +2307,16 @@ def Depends(  # noqa: N802
         return commons
     ```
     """
+
+    # Handle case when `scope` parameter value is invalid
+    if scope not in ("function", "request", None):
+        raise FastAPIError(
+            "Invalid value for 'scope' parameter in Depends(). "
+            "Expected 'function', 'request', or None. "
+            f'Did you mean to use Security(dependency_fn, oauth_scopes="{scope}") '
+            "to specify OAuth2 scopes instead?"
+        )
+
     return params.Depends(dependency=dependency, use_cache=use_cache, scope=scope)
 
 
@@ -2495,6 +2505,14 @@ def Security(  # noqa: N802
             "oauth_scopes='your_scope'."
         )
 
+    # Handle case when `scope` parameter value is invalid
+    if scope not in ("function", "request", None):
+        raise FastAPIError(
+            "Invalid value for 'scope' parameter in Security(). "
+            "Expected 'function', 'request', or None. "
+            f'Did you mean oauth_scopes="{scope}" to specify OAuth2 scopes instead?'
+        )
+
     return params.Security(
         dependency=dependency,
         oauth_scopes=oauth_scopes,
diff --git a/tests/test_security_scopes_parameter.py b/tests/test_security_scopes_parameter.py
index d893bbbf2..66ca70a41 100644
--- a/tests/test_security_scopes_parameter.py
+++ b/tests/test_security_scopes_parameter.py
@@ -1,5 +1,5 @@
 import pytest
-from fastapi import Security
+from fastapi import Depends, Security
 from fastapi.exceptions import FastAPIError
 
 
@@ -35,3 +35,33 @@ def test_pass_scope_as_scopes(value: str):
         "Expected a sequence of strings (e.g., ['admin', 'user']), but received a single string. "
         f'Did you mean to use scope="{value}" to specify when the exit code of dependencies with yield should run? '
     )
+
+
+def test_pass_invalid_scope_value_to_security():
+    """
+    Test passing invalid value to `scope` parameter in `Security`.
+    """
+
+    with pytest.raises(FastAPIError) as exc_info:
+        Security(dependency=lambda: None, scope="invalid_scope")
+
+    assert str(exc_info.value) == (
+        "Invalid value for 'scope' parameter in Security(). "
+        "Expected 'function', 'request', or None. "
+        'Did you mean oauth_scopes="invalid_scope" to specify OAuth2 scopes instead?'
+    )
+
+
+def test_pass_invalid_scope_value_to_depends():
+    """
+    Test passing invalid value to `scope` parameter in `Depends`.
+    """
+
+    with pytest.raises(FastAPIError) as exc_info:
+        Depends(dependency=lambda: None, scope="invalid_scope")
+
+    assert str(exc_info.value) == (
+        "Invalid value for 'scope' parameter in Depends(). "
+        "Expected 'function', 'request', or None. "
+        'Did you mean to use Security(dependency_fn, oauth_scopes="invalid_scope") to specify OAuth2 scopes instead?'
+    )