{"record":{"id":"358a4bee3a394fc4","repo":"agentscope-ai/agentscope","slug":"x-user-id-header-is-required","errorCode":null,"errorMessage":"X-User-ID header is required.","messagePattern":"X-User-ID header is required\\.","errorType":"http","errorClass":"HTTPException","httpStatus":401,"severity":"error","filePath":"src/agentscope/app/deps.py","lineNumber":50,"sourceCode":"async def get_current_user_id(\n    x_user_id: str = Header(\n        description=\"Caller's user ID. \"\n        \"Temporary header-based identity; will be replaced by JWT auth.\",\n    ),\n) -> str:\n    \"\"\"Return the caller's user ID from the ``X-User-ID`` request header.\n\n    Args:\n        x_user_id (`str`): Value of the ``X-User-ID`` header.\n\n    Returns:\n        `str`: The authenticated user ID.\n\n    Raises:\n        `HTTPException`: 401 if the header is missing or empty.\n    \"\"\"\n    if not x_user_id:\n        raise HTTPException(\n            status_code=status.HTTP_401_UNAUTHORIZED,\n            detail=\"X-User-ID header is required.\",\n        )\n    return x_user_id\n\n\nasync def get_storage(request: Request) -> StorageBase:\n    \"\"\"Return the application-wide storage backend.\n\n    Args:\n        request (`Request`): The incoming FastAPI request.\n\n    Returns:\n        `StorageBase`: The storage instance stored in ``app.state``.\n    \"\"\"\n    return request.app.state.storage\n\n","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/app/deps.py#L32-L68","documentation":"HTTPException 401 raised by the get_current_user_id FastAPI dependency when the X-User-ID request header is absent or empty. This lightweight auth scheme identifies users purely by that header, so a missing header means the request is unauthenticated and every endpoint using the dependency rejects it.","triggerScenarios":"Calling any app endpoint that depends on get_current_user_id (as a FastAPI Depends) without the X-User-ID header, or with an empty value — e.g. curl without -H 'X-User-ID: ...', gateway/proxy stripping the header, or frontend not sending it.","commonSituations":"Reverse proxy or auth middleware not forwarding custom headers, typos/case issues in header name (though HTTP headers are case-insensitive), integration tests forgetting the header, switching from token auth and assuming identity comes from elsewhere.","solutions":["Send a non-empty X-User-ID header on every request (e.g. -H 'X-User-ID: user123')","Configure your proxy/gateway to forward the header (proxy_set_header X-User-ID $http_x_user_id in nginx)","In tests, add the header to the client fixture defaults","If you need real auth, wrap the app with middleware that derives X-User-ID from your session/token"],"exampleFix":"# before\nresp = client.get(\"/api/skills\")\n\n# after\nresp = client.get(\"/api/skills\", headers={\"X-User-ID\": \"user123\"})","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"resp = client.get(\"/api/...\")\nif resp.status_code == 401 and \"X-User-ID\" in resp.json().get(\"detail\", \"\"):\n    retry_with_header()","preventionTips":["Set the X-User-ID header in a shared HTTP client default/interceptor","Configure proxies to forward custom X- headers","Add the header to test client fixtures once"],"tags":["http","auth","header","fastapi"],"backgroundTag":"missing-auth-header","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}