{"record":{"id":"0b8770dda1626ff3","repo":"PrefectHQ/fastmcp","slug":"claim-self-claim-name-not-found-in-access-toke","errorCode":null,"errorMessage":"Claim '{self.claim_name}' not found in access token. Available claims: {list(token.claims.keys())}","messagePattern":"Claim '(.+?)' not found in access token\\. Available claims: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"fastmcp_slim/fastmcp/server/dependencies.py","lineNumber":1346,"sourceCode":"\n# --- Token Claim dependency ---\n\n\nclass _TokenClaim(Dependency[str]):\n    \"\"\"Dependency that extracts a specific claim from the access token.\"\"\"\n\n    def __init__(self, claim_name: str):\n        self.claim_name = claim_name\n\n    async def __aenter__(self) -> str:\n        token = get_access_token()\n        if token is None:\n            raise RuntimeError(\n                f\"No access token available. Cannot extract claim '{self.claim_name}'.\"\n            )\n        value = token.claims.get(self.claim_name)\n        if value is None:\n            raise RuntimeError(\n                f\"Claim '{self.claim_name}' not found in access token. \"\n                f\"Available claims: {list(token.claims.keys())}\"\n            )\n        return str(value)\n\n    async def __aexit__(\n        self,\n        exc_type: type[BaseException] | None,\n        exc_value: BaseException | None,\n        traceback: TracebackType | None,\n    ) -> None:\n        pass\n\n\ndef TokenClaim(name: str) -> str:\n    \"\"\"Get a specific claim from the access token.\n\n    This dependency extracts a single claim value from the current access token.","sourceCodeStart":1328,"sourceCodeEnd":1364,"githubUrl":"https://github.com/PrefectHQ/fastmcp/blob/1f021142978e0861cd910c8df4e8074bc7cf3978/fastmcp_slim/fastmcp/server/dependencies.py#L1328-L1364","documentation":"The Claim dependency found a valid access token, but token.claims.get(claim_name) returned None, so it raises this RuntimeError listing the claims that ARE present. FastMCP distinguishes this from the no-token case so you can tell an auth setup problem from a claim-name/schema mismatch. Note it also fires when the claim exists but its value is None or falsy-None, since only None triggers the branch.","triggerScenarios":"Entering `with Claim(\"roles\")` when the token's claims dict has no \"roles\" key; the auth provider issues tokens with different claim names (e.g. \"scope\" vs \"scopes\", OIDC \"preferred_username\" vs custom \"username\"); the claim value is literally null in the JWT payload.","commonSituations":"Switching identity providers (Auth0 → Keycloak) with different claim vocabularies; forgetting that ID token claims vs access token claims differ; typos in claim names; token templates/mappings not configured on the auth server.","solutions":["Inspect the Available claims list in the message and correct the claim name in your Claim(...) call","Decode the actual token (jwt.io or logs) to see the real claim keys your auth provider emits","Configure the auth provider to include the needed claim in the access token (mappers/scope mappings)","If the claim is optional, use get_access_token() and token.claims.get(name, default) instead"],"exampleFix":"// before\nasync def role() -> str:\n    with Claim(\"role\") as r:  # token only has 'roles'\n        return r\n// after\nasync def role() -> str:\n    with Claim(\"roles\") as r:\n        return r","handlingStrategy":"fallback","validationCode":"from fastmcp.server.dependencies import get_access_token\ntoken = get_access_token()\nvalue = token.claims.get('sub') if token else None\nif value is None:\n    ...  # fallback or error before raising","typeGuard":"from fastmcp.server.dependencies import get_access_token\n\ndef get_claim(name: str) -> str | None:\n    token = get_access_token()\n    v = token.claims.get(name) if token else None\n    return str(v) if v is not None else None","tryCatchPattern":"try:\n    async with Claim('roles') as roles:\n        return roles.split()\nexcept RuntimeError as e:\n    if 'not found in access token' in str(e):\n        logger.warning('claims available: check message for actual keys')\n        return []","preventionTips":["Read the Available claims list in the message — it tells you the exact keys present","Match claim names to your identity provider's actual token payload (decode the JWT)","Configure provider claim mappings rather than renaming claims in code","Prefer get_access_token().claims.get(name, default) for optional claims"],"tags":["auth","jwt","claims","fastmcp"],"backgroundTag":"jwt-claim-not-found","analyzedSha":"1f021142978e0861cd910c8df4e8074bc7cf3978","analyzedAt":"2026-08-29T14:31:16.082Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}