langchain-ai/langgraph · error · ValueError

Auth handler ' ' must have a 'ctx: AuthContext' parameter…

Error message

Auth handler '{getattr(fn, '__name__', fn)}' must have a 'ctx: AuthContext' parameter. Update the function signature to include this required parameter.

What it means

Signature check inside _validate_handler, run at decoration time for @auth.authenticate and @auth.on handlers. It inspects the function signature and rejects handlers whose parameters do not include 'ctx', which carries the AuthContext (user identity, permissions) needed to make authorization decisions.

Solutions

1. Add a ctx parameter to the handler: async def handler(ctx: AuthContext, value): ...
2. Import AuthContext from langgraph_sdk.auth.types for the annotation if desired

When it happens

Trigger: Thrown at libs/sdk-py/langgraph_sdk/auth/__init__.py:855 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of langchain-ai/langgraph@38031739e5 (2026-08-26). Data as JSON: /api/errors/3b0e5fa07ca55240. Report an issue: GitHub.

Appendix: source

Thrown at libs/sdk-py/langgraph_sdk/auth/__init__.py:855

def _validate_handler(fn: Callable[..., typing.Any]) -> None:
    """Validates that an auth handler function meets the required signature.

    Auth handlers must:
    1. Be async functions
    2. Accept a ctx parameter of type AuthContext
    3. Accept a value parameter for the data being authorized
    """
    if not inspect.iscoroutinefunction(fn):
        raise ValueError(
            f"Auth handler '{getattr(fn, '__name__', fn)}' must be an async function. "
            "Add 'async' before 'def' to make it asynchronous and ensure"
            " any IO operations are non-blocking."
        )

    sig = inspect.signature(fn)
    if "ctx" not in sig.parameters:
        raise ValueError(
            f"Auth handler '{getattr(fn, '__name__', fn)}' must have a 'ctx: AuthContext' parameter. "
            "Update the function signature to include this required parameter."
        )
    if "value" not in sig.parameters:
        raise ValueError(
            f"Auth handler '{getattr(fn, '__name__', fn)}' must have a 'value' parameter. "
            " The value contains the mutable data being sent to the endpoint."
            "Update the function signature to include this required parameter."
        )


def is_studio_user(
    user: types.MinimalUser | types.BaseUser | types.MinimalUserDict,
) -> bool:
    return isinstance(user, types.StudioUser) or (
        isinstance(user, dict) and user.get("kind") == "StudioUser"
    )

View on GitHub (pinned to 38031739e5)