{"record":{"id":"51c084b61f424653","repo":"spring-projects/spring-security","slug":"an-error-occurred-while-attempting-to-decode-the-j-51c084","errorCode":null,"errorMessage":"An error occurred while attempting to decode the Jwt: %s","messagePattern":"An error occurred while attempting to decode the Jwt: (.+?)","errorType":"exception","errorClass":"BadJwtException","httpStatus":null,"severity":"error","filePath":"oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/NimbusJwtDecoder.java","lineNumber":158,"sourceCode":"\t\tJWT jwt = parse(token);\n\t\tif (jwt instanceof PlainJWT) {\n\t\t\tthis.logger.trace(\"Failed to decode unsigned token\");\n\t\t\tthrow new BadJwtException(\"Unsupported algorithm of \" + jwt.getHeader().getAlgorithm());\n\t\t}\n\t\tJwt createdJwt = createJwt(token, jwt);\n\t\treturn validateJwt(createdJwt);\n\t}\n\n\tprivate JWT parse(String token) {\n\t\ttry {\n\t\t\treturn JWTParser.parse(token);\n\t\t}\n\t\tcatch (Exception ex) {\n\t\t\tthis.logger.trace(\"Failed to parse token\", ex);\n\t\t\tif (ex instanceof ParseException) {\n\t\t\t\tthrow new BadJwtException(String.format(DECODING_ERROR_MESSAGE_TEMPLATE, \"Malformed token\"), ex);\n\t\t\t}\n\t\t\tthrow new BadJwtException(String.format(DECODING_ERROR_MESSAGE_TEMPLATE, ex.getMessage()), ex);\n\t\t}\n\t}\n\n\tprivate Jwt createJwt(String token, JWT parsedJwt) {\n\t\ttry {\n\t\t\t// Verify the signature\n\t\t\tJWTClaimsSet jwtClaimsSet = this.jwtProcessor.process(parsedJwt, null);\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\t// @formatter:off\n\t\t\treturn Jwt.withTokenValue(token)\n\t\t\t\t\t.headers((h) -> h.putAll(headers))\n\t\t\t\t\t.claims((c) -> c.putAll(claims))\n\t\t\t\t\t.build();\n\t\t\t// @formatter:on\n\t\t}\n\t\tcatch (RemoteKeySourceException ex) {\n\t\t\tthis.logger.trace(\"Failed to retrieve JWK set\", ex);","sourceCodeStart":140,"sourceCodeEnd":176,"githubUrl":"https://github.com/spring-projects/spring-security/blob/96852e8860138a482cb13d1479573f24ff6443c6/oauth2/oauth2-jose/src/main/java/org/springframework/security/oauth2/jwt/NimbusJwtDecoder.java#L140-L176","documentation":"parse() also handles non-ParseException failures from JWTParser.parse (e.g. IllegalStateException, IllegalCallerException, IO errors on nested objects); it wraps the underlying exception message into BadJwtException via the DECODING_ERROR_MESSAGE_TEMPLATE. The %s is filled with ex.getMessage().","triggerScenarios":"decode() → parse(token) where parsing throws a RuntimeException other than ParseException — e.g. nested/serialized JSON claims that fail to deserialize, illegal header parameter combinations detected by Nimbus.","commonSituations":"Tokens with non-standard nested claim encodings; corrupted JWTs whose structure parses superficially but fails deeper validation; custom Nimbus configuration or version differences changing parse behavior.","solutions":["Read the wrapped message (and cause) to identify the specific parse failure; log the exception chain server-side.","Regenerate the token from the authorization server and compare headers/claims with the failing token.","Ensure token claims use standard JSON types; avoid exotic claim serialization on the issuer side.","Catch BadJwtException and reject the request with 401 invalid_token."],"exampleFix":"// before\ncatch (BadJwtException e) { /* message ignored */ }\n// after\ncatch (BadJwtException e) {\n    logger.warn(\"JWT rejected: {} cause={}\", e.getMessage(), e.getCause(), e);\n    // return 401 with WWW-Authenticate: Bearer error=\"invalid_token\"\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { return jwtDecoder.decode(token); }\ncatch (BadJwtException e) {\n    log.warn(\"JWT parse failure: {}\", e.getMessage(), e.getCause());\n    // respond 401 invalid_token\n}","preventionTips":["Log the full exception chain (BadJwtException + cause) to identify the underlying Nimbus failure","Keep Nimbus and Spring Security versions aligned to avoid parse-behavior surprises","Issue tokens with standard claim types only; avoid non-standard nested serialization"],"tags":["jwt","parsing","deserialization"],"backgroundTag":"invalid-token-format","analyzedSha":"96852e8860138a482cb13d1479573f24ff6443c6","analyzedAt":"2026-09-10T23:25:23.477Z","contentChangedAt":"2026-09-10T23:25:23.477Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}