alibaba/nacos · error · AccessException

Invalid token format:

Error message

Invalid token format: 

What it means

Thrown from catch(IllegalArgumentException | NullPointerException) when the token data itself is internally inconsistent in a way the processor surfaces as IAE/NPE — e.g. a null token slipping past the blank check via a non-String path, or a token with empty segments. The original exception message is appended.

Source

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

            
            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());
        }
    }
    
    private ConfigurableJWTProcessor<SecurityContext> getJwtProcessor() throws AccessException {
        if (jwtProcessor == null) {
            synchronized (this) {
                if (jwtProcessor == null) {
                    try {
                        jwtProcessor = createJwtProcessor(jwksProvider.getJwkSet());
                    } catch (IOException e) {
                        throw new AccessException(
                            "Failed to initialize JWT processor: " + e.getMessage());
                    }
                }

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Inspect the appended message (e.g. '...: null key') to locate the exact invalid data.
2. Validate the token has exactly two dots and three non-empty base64URL segments before submitting.
3. Re-issue the token from a conformant IdP/encoder.
4. Decode the token payload manually to confirm it is a JSON object.
5. Check the server log 'Invalid token data: ...' which includes the full stack trace.

Example fix

// before
validator.validate("eyJhbGci.eyJzdWIi."); // empty signature segment

// after: reject malformed tokens before validation
if (token == null || token.split("\\.").length != 3
        || Arrays.stream(token.split("\\.")).anyMatch(String::isEmpty)) {
    throw new AccessException("Malformed JWT structure");
}
validator.validate(token);

boolean wellFormedSegments(String t) {
    if (t == null) return false;
    String[] s = t.split("\\.");
    return s.length == 3 && !s[0].isEmpty() && !s[1].isEmpty() && !s[2].isEmpty();
}
if (!wellFormedSegments(token)) {
    throw new AccessException("Malformed JWT");
}

try {
    validator.validate(token);
} catch (AccessException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Invalid token format: ")) {
        // appended IAE/NPE reason guides the fix
    }
    throw e;
}

When it happens

Trigger: processor.process() or a downstream call raises IllegalArgumentException/NullPointerException: token has zero-length signature segment, the JSON object claim is malformed into an unexpected type, or a library-internal null check trips.

Common situations: A token like 'header.payload.' (empty signature), a token where the payload JSON is not an object, or a token produced by a non-standard encoder that emits segments NimbusDS does not tolerate.

Understand the failure class

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

Related errors

• token invalid!
• invalid token, username is empty
• Token is required
• No valid OIDC token found
• Plugin config value cannot be null:

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