{"record":{"id":"c7091f17168a7b79","repo":"spring-projects/spring-security","slug":"an-error-occurred-while-attempting-to-decode-the-j-c7091f","errorCode":null,"errorMessage":"An error occurred while attempting to decode the Jwt: + ex.getMessage()","messagePattern":"An error occurred while attempting to decode the Jwt: \\+ ex\\.getMessage\\(\\)","errorType":"exception","errorClass":"JwtException","httpStatus":null,"severity":"error","filePath":"oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/NimbusReactiveJwtDecoder.java","lineNumber":179,"sourceCode":"\t\t\t\t\t\"An error occurred while attempting to decode the Jwt: \" + ex.getMessage(), ex));\n\t\t}\n\t}\n\n\tprivate Mono<Jwt> decode(JWT parsedToken) {\n\t\ttry {\n\t\t\t// @formatter:off\n\t\t\treturn this.jwtProcessor.convert(parsedToken)\n\t\t\t\t\t.map((set) -> createJwt(parsedToken, set))\n\t\t\t\t\t.map(this::validateJwt)\n\t\t\t\t\t.onErrorMap((ex) -> !(ex instanceof IllegalStateException) && !(ex instanceof JwtException),\n\t\t\t\t\t\t\t(ex) -> new JwtException(\"An error occurred while attempting to decode the Jwt: \", ex));\n\t\t\t// @formatter:on\n\t\t}\n\t\tcatch (JwtException ex) {\n\t\t\tthrow ex;\n\t\t}\n\t\tcatch (RuntimeException ex) {\n\t\t\tthrow new JwtException(\"An error occurred while attempting to decode the Jwt: \" + ex.getMessage(), ex);\n\t\t}\n\t}\n\n\tprivate Jwt createJwt(JWT parsedJwt, JWTClaimsSet jwtClaimsSet) {\n\t\ttry {\n\t\t\tMap<String, Object> headers = new LinkedHashMap<>(parsedJwt.getHeader().toJSONObject());\n\t\t\tMap<String, Object> claims = this.claimSetConverter.convert(jwtClaimsSet.getClaims());\n\t\t\treturn Jwt.withTokenValue(parsedJwt.getParsedString())\n\t\t\t\t.headers((h) -> h.putAll(headers))\n\t\t\t\t.claims((c) -> c.putAll(claims))\n\t\t\t\t.build();\n\t\t}\n\t\tcatch (Exception ex) {\n\t\t\tthrow new BadJwtException(\"An error occurred while attempting to decode the Jwt: \" + ex.getMessage(), ex);\n\t\t}\n\t}\n\n\tprivate Jwt validateJwt(Jwt jwt) {","sourceCodeStart":161,"sourceCodeEnd":197,"githubUrl":"https://github.com/spring-projects/spring-security/blob/96852e8860138a482cb13d1479573f24ff6443c6/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/NimbusReactiveJwtDecoder.java#L161-L197","documentation":"NimbusReactiveJwtDecoder.decode() catches JwtException and rethrows it unchanged, but any other RuntimeException during token parsing/processing is wrapped in a new JwtException with this message. It means an unexpected runtime problem (not a normal validation failure) occurred while decoding: malformed token text fed to nimbus-jose-jwt's SignedJWT.parse, JSON/serialization surprises, NPEs, or downstream reactive errors. Normal expired/invalid-signature errors surface as their own JwtValidationException/ BadJwtException instead.","triggerScenarios":"decode(token) with a token string that is not valid compact JWS/JWE serialization (empty, truncated, or arbitrary text), a token whose header/claims JSON breaks parsing, or a custom JwtDecoder configuration (e.g. misconfigured JWKSource/processor) throwing NPE/IllegalStateException during processing.","commonSituations":"Sending a raw access token from a non-JWT flow (opaque token) to a JWT decoder; tokens truncated by proxies or logging round-trips; JWK set endpoint returning HTML/error pages that break key fetching; missing clock/validator config causing NPEs in older Spring Security versions; base64url-corrupted tokens stored in cookies.","solutions":["Log the received token's structure (header claims via getClaims()) before decoding — confirm it has three dot-separated base64url segments.","Inspect getCause(): the original RuntimeException pinpoints the real failure (parse error, NPE, network fetch of the JWK set).","Verify the client is not sending an opaque token; if it is, use an OpaqueTokenIntrospector instead of NimbusReactiveJwtDecoder.","Check the jwkSetUri/jwkSource endpoint returns valid JWK Set JSON (application/json) and is reachable from the decoder."],"exampleFix":"// before\njwtDecoder.decode(rawToken); // rawToken may be opaque\n// after\nif (rawToken.chars().filter(c -> c == '.').count() == 2) {\n    jwtDecoder.decode(rawToken);\n} else {\n    return Mono.error(new InvalidBearerTokenException(\"Token is not a JWT\"));\n}","handlingStrategy":"try-catch","validationCode":"// reject obviously non-JWT tokens before calling decode\nstatic boolean looksLikeJwt(String token) {\n    return token != null && token.chars().filter(c -> c == '.').count() == 2;\n}","typeGuard":null,"tryCatchPattern":"try {\n    return jwtDecoder.decode(token).block();\n} catch (BadJwtException ex) {\n    throw new InvalidBearerTokenException(\"Malformed token\");\n} catch (JwtValidationException ex) {\n    throw new OAuth2TokenValidationException(\"Token failed validation\", ex);\n} catch (JwtException ex) {\n    // message begins \"An error occurred while attempting to decode the Jwt\"\n    logger.warn(\"Unexpected decode failure\", ex.getCause());\n    throw new InvalidBearerTokenException(\"Token could not be processed\");\n}","preventionTips":["Verify the authorization server actually issues JWTs (not opaque tokens) before wiring a JWT decoder.","Ensure the jwkSetUri endpoint is reachable and returns a valid JWK Set JSON document.","Never let tokens pass through transformations (logging, cookie encode) that corrupt base64url text.","Keep decoder configuration (validators, processors) minimal and null-safe; test with a real issued token in CI."],"tags":["jwt","decoding","spring-security","reactive","malformed-token"],"backgroundTag":"invalid-argument-format","analyzedSha":"96852e8860138a482cb13d1479573f24ff6443c6","analyzedAt":"2026-09-10T23:25:23.477Z","contentChangedAt":"2026-09-10T23:25:23.477Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}