alibaba/nacos · error · AccessException

Invalid token format

Error message

Invalid token format

What it means

Thrown from the catch(ParseException) branch when the NimbusDS JWT parser cannot parse the token string into a structured JWT. It means the string is present but is not a syntactically valid JWT (three base64URL segments separated by dots).

Source

Thrown at plugin-default-impl/nacos-oidc-auth-plugin/src/main/java/com/alibaba/nacos/plugin/auth/impl/oidc/token/JwtTokenValidator.java:108

        }
        
        try {
            // Ensure processor is initialized (lazy init)
            ConfigurableJWTProcessor<SecurityContext> processor = getJwtProcessor();
            
            // Process and validate the token (Parsing also happens inside process but we parse handled inside)
            // Note: process(String) parses it.
            JWTClaimsSet claims = processor.process(token, null);
            
            // Additional validation
            validateClaims(claims);
            
            LOGGER.debug("Token validated successfully for subject: {}", claims.getSubject());
            return claims;
            
        } catch (ParseException e) {
            LOGGER.warn("Failed to parse JWT token: {}", e.getMessage());
            throw new AccessException("Invalid token format");
        } catch (BadJOSEException e) {
            LOGGER.warn("JWT signature verification failed: {}", e.getMessage());
            // Try refreshing JWKS and retry once (key rotation scenario)
            return retryWithRefreshedJwks(token, e);
        } catch (JOSEException e) {
            LOGGER.warn("JWT processing error: {}", e.getMessage());
            throw new AccessException("Token processing error");
        } catch (AccessException e) {
            throw e;
        } catch (IllegalArgumentException | NullPointerException e) {
            LOGGER.error("Invalid token data: {}", e.getMessage(), e);
            throw new AccessException("Invalid token format: " + e.getMessage());
        } catch (Exception e) {
            LOGGER.error("Unexpected error during token validation: {} - {}",
                e.getClass().getSimpleName(), e.getMessage(), e);
            throw new AccessException("Token validation failed: " + e.getClass().getSimpleName());
        }
    }

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Confirm the token is actually a JWT (decodes at jwt.io, has three dot-separated segments).
2. Check the plugin config token-validation-method matches the token type the IdP issues (jwt vs introspection).
3. If the IdP issues opaque tokens, switch token-validation-method to 'introspection'.
4. Inspect server logs for 'Failed to parse JWT token: ...' which carries the parser's reason.
5. Verify the token is not being double-encoded or whitespace-trimmed incorrectly in transit.

Example fix

# before (IdP issues opaque tokens, plugin expects JWT)
nacos.plugin.auth.oidc.token-validation-method=jwt

# after
nacos.plugin.auth.oidc.token-validation-method=introspection

boolean looksLikeJwt(String t) {
    return t != null && t.split("\\.").length == 3;
}
if (!looksLikeJwt(token)) {
    throw new AccessException("Token is not a JWT");
}

try {
    JWTClaimsSet claims = validator.validate(token);
} catch (AccessException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Invalid token format")) {
        // 401 malformed/unsupported token; advise client to use a JWT
    }
    throw e;
}

When it happens

Trigger: processor.process(token) raises ParseException because the token is not a JWT: an opaque token, a truncated token, a base64-malformed payload, or a non-JSON claims segment.

Common situations: Client sent an opaque/session reference token while the plugin is configured for token-validation-method=jwt; the token was URL-decoded incorrectly and corrupted; copy/paste truncated the token; the IdP was pointed at the wrong token endpoint returning HTML/error text.

Understand the failure class

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

Related errors

• OIDC discovery response is empty
• Failed to parse OIDC configuration
• Failed to parse JWKS
• Token is empty
• Token processing error

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/0da9db60f2af89cf. Report an issue: GitHub.