bytedance/deer-flow · error · HTTPException

Authentication required

Error message

Authentication required

What it means

HTTP 401 from AuthContext.require_user() when the context exists but holds no authenticated User. require_user is the imperative 'get user or die' accessor used inside handlers that already have an AuthContext; a None user means the request was anonymous or authentication failed upstream.

Source

Thrown at backend/app/gateway/authz.py:111

        Args:
            resource: Resource name (e.g., "threads")
            action: Action name (e.g., "read")

        Returns:
            True if user has permission
        """
        permission = f"{resource}:{action}"
        return permission in self.permissions

    def require_user(self) -> User:
        """Get user or raise 401.

        Raises:
            HTTPException 401 if not authenticated
        """
        if not self.user:
            raise HTTPException(status_code=401, detail="Authentication required")
        return self.user


def get_auth_context(request: Request) -> AuthContext | None:
    """Get AuthContext from request state."""
    return getattr(request.state, "auth", None)


_ALL_PERMISSIONS: list[str] = [
    Permissions.THREADS_READ,
    Permissions.THREADS_WRITE,
    Permissions.THREADS_DELETE,
    Permissions.RUNS_CREATE,
    Permissions.RUNS_READ,
    Permissions.RUNS_CANCEL,
]

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Ensure the route is wrapped in require_auth/require_permission so the request is authenticated before require_user is reachable
2. Check auth_context.user or auth_context.is_authenticated before calling require_user when anonymous access is possible
3. Send a valid Authorization header / session cookie in the client request

Example fix

# before
user = auth_context.require_user()
# after
if not auth_context.is_authenticated:
    raise HTTPException(status_code=401, detail="Authentication required")
user = auth_context.require_user()

def has_user(ctx: AuthContext) -> bool:
    """True when require_user() will succeed."""
    return ctx.user is not None

from fastapi import HTTPException
try:
    user = auth_context.require_user()
except HTTPException as e:
    if e.status_code == 401:
        raise NotAuthenticated()  # convert to a 302 to /login for browser routes
    raise

When it happens

Trigger: Calling auth_context.require_user() on an AuthContext whose user attribute is None — e.g. anonymous request where middleware attached an unauthenticated context, or an API-key/service identity that authenticates without a User record.

Common situations: Adding new endpoints that assume a user is always present; auth middleware misconfiguration letting anonymous contexts reach the handler; service-to-service calls that authenticate as the internal identity rather than a User.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Permission denied: {resource}:{action}
• Thread {thread_id} not found
• NOT_AUTHENTICATED
• USER_NOT_FOUND
• Token error: {payload.value}

AI-assisted analysis of bytedance/deer-flow@1dd6ba1acb (2026-08-14). Data as JSON: /api/errors/137d56536661b3ad. Report an issue: GitHub.