zeroclaw-labs/zeroclaw · error

Userinfo response has missing or empty `sub` claim

Error message

Userinfo response has missing or empty `sub` claim

What it means

The userinfo endpoint answered 2xx but the sub field is empty or whitespace (nevis.rs:279-281). ZeroClaw requires sub as the user identifier and fails closed. This indicates an IdP-side claim problem, not a bad token.

Source

Thrown at crates/zeroclaw-runtime/src/security/nevis.rs:280

            .bearer_auth(session_token)
            .send()
            .await
            .context("Failed to reach Nevis userinfo endpoint")?;

        if !resp.status().is_success() {
            bail!(
                "Nevis session validation returned HTTP {}",
                resp.status().as_u16()
            );
        }

        let body: UserInfoResponse = resp
            .json()
            .await
            .context("Failed to parse Nevis userinfo response")?;

        if body.sub.trim().is_empty() {
            bail!("Userinfo response has missing or empty `sub` claim");
        }

        let now = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .unwrap_or_default()
            .as_secs();

        let mut roles = body.realm_access.map(|ra| ra.roles).unwrap_or_default();
        roles.sort();
        roles.dedup();

        let identity = NevisIdentity {
            user_id: body.sub,
            roles,
            scopes: body
                .scope
                .unwrap_or_default()
                .split_whitespace()

View on GitHub (pinned to 88bb9c8533)

Solutions

1. Capture a raw userinfo response for a real user token and confirm sub is populated
2. Fix the IdP client/protocol mappers so sub is emitted on userinfo
3. If tokens without sub are legitimate in your setup, filter them before they reach validate_session

Match err.to_string().contains("`sub` claim") and treat it as an IdP misconfiguration: return 503, page an admin, and do not log the affected user out of other flows.

When it happens

Trigger: validate_session against an IdP deployment whose userinfo does not map the subject claim; a service or anonymized token with no subject; a custom claim mapper that nulls sub.

Common situations: Nevis realm userinfo mapper misconfiguration; token issued for a service account without sub; a federation bridge that drops the sub claim.

Related errors

• empty bearer token
• MFA is required but user '{}' has not completed MFA verifica
• Nevis session expired
• Nevis introspection returned HTTP {}
• Token is not active (revoked or expired)

AI-assisted analysis of zeroclaw-labs/zeroclaw@88bb9c8533 (2026-08-23). Data as JSON: /api/errors/6ef66a1c0e31913d. Report an issue: GitHub.