gofr-dev/gofr · error

claim key not found

Error message

claim key not found

What it means

errClaimKeyNotFound is returned by extractArrayClaim when the key preceding the bracket notation (e.g. "roles" in "roles[0]") does not exist in the JWT claims map. It means the token's claims simply do not contain the named key that the array-notation path points at. Callers see it wrapped as "failed to extract role from JWT: claim key not found: <key>".

Source

Thrown at pkg/gofr/rbac/middleware.go:65

	ErrRoleNotFound = errors.New("unauthorized: role not found")

	// errJWTClaimsNotFound is returned when JWT claims are not found in request context.
	errJWTClaimsNotFound = errors.New("JWT claims not found in request context")

	// errEmptyClaimPath is returned when claim path is empty.
	errEmptyClaimPath = errors.New("empty claim path")

	// errClaimPathNotFound is returned when a claim path is not found in JWT claims.
	errClaimPathNotFound = errors.New("claim path not found")

	// errInvalidArrayNotation is returned when array notation is invalid.
	errInvalidArrayNotation = errors.New("invalid array notation")

	// errInvalidArrayIndex is returned when array index is invalid.
	errInvalidArrayIndex = errors.New("invalid array index")

	// errClaimKeyNotFound is returned when a claim key is not found.
	errClaimKeyNotFound = errors.New("claim key not found")

	// errClaimValueNotArray is returned when a claim value is not an array.
	errClaimValueNotArray = errors.New("claim value is not an array")

	// errArrayIndexOutOfBounds is returned when array index is out of bounds.
	errArrayIndexOutOfBounds = errors.New("array index out of bounds")

	// errInvalidClaimStructure is returned when claim structure is invalid.
	errInvalidClaimStructure = errors.New("invalid claim structure")

	// errAuthorizationError is returned as a generic error message for unknown errors in traces.
	errAuthorizationError = errors.New("authorization error")
)

// Middleware creates an HTTP middleware function that enforces RBAC authorization.
// It extracts the user's role and checks if the role is allowed for the requested route.
//
//nolint:gocognit,gocyclo // Middleware complexity is acceptable due to multiple authorization paths

View on GitHub (pinned to 187eb24962)

Solutions

1. Decode the actual token (e.g. jwt.io) and confirm the key used in JWTClaimPath exists in the claims payload.
2. Update Config.JWTClaimPath to match the real claim name emitted by your identity provider.
3. Add/restore the claim in the identity provider's token mapper/client configuration so tokens include it.
4. Verify requests are hitting the intended issuer/realm — a different realm may omit the claim.

Example fix

// before (token has "groups", config expects "roles")
config.JWTClaimPath = "roles[0]"
// after
config.JWTClaimPath = "groups[0]"

func tokenHasClaim(claims jwt.MapClaims, key string) bool {
    _, ok := claims[key]
    return ok
}
// before relying on the middleware, decode a sample token and assert:
// if !tokenHasClaim(sampleClaims, "roles") { log.Fatal("IdP token missing 'roles' claim") }

func claimPresent(claims jwt.MapClaims, key string) bool {
    v, ok := claims[key]
    return ok && v != nil
}

if err := nextErr; err != nil && strings.Contains(err.Error(), "claim key not found") {
    logger.Warn("token missing configured role claim — check IdP token mappers", "err", err)
    http.Error(w, "unauthorized", http.StatusUnauthorized)
    return
}

When it happens

Trigger: JWTClaimPath like "roles[0]" while the incoming token's claims have no "roles" key at all — e.g. token issued without the roles claim, wrong issuer/realm, or path pointing at a renamed claim; the claims map lookup claims[key] fails with ok=false.

Common situations: Identity provider (Keycloak, Auth0, etc.) configured without the role claim in token mappers; after rotating to a new client whose token template dropped the claim; mismatch between configured path and actual claim names; testing with hand-crafted tokens missing claims.

Related errors

• claim value is not an array
• array index out of bounds
• invalid claim structure
• failed to extract role from JWT: %w
• %w: %s

AI-assisted analysis of gofr-dev/gofr@187eb24962 (2026-09-01). Data as JSON: /api/errors/91a3eb5feb169678. Report an issue: GitHub.