{"record":{"id":"2f3118b59e616295","repo":"jwtk/jjwt","slug":"unexpected-content-jws","errorCode":null,"errorMessage":"Unexpected content JWS.","messagePattern":"Unexpected content JWS\\.","errorType":"exception","errorClass":"UnsupportedJwtException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/io/jsonwebtoken/SupportedJwtVisitor.java","lineNumber":129,"sourceCode":"            Assert.stateIsInstance(Claims.class, payload, \"Unexpected payload data type: \");\n            return onVerifiedClaims((Jws<Claims>) jws);\n        }\n    }\n\n    /**\n     * Handles an encountered JWS message that has been cryptographically verified/authenticated and has\n     * a byte[] array payload. If the JWT creator has set the (optional) {@link Header#getContentType()} value, the\n     * application may inspect that value to determine how to convert the byte array to the final type as desired.\n     *\n     * <p>The default implementation immediately throws an {@link UnsupportedJwtException}; it is expected that\n     * subclasses will override this method if the application needs to support this type of JWT.</p>\n     *\n     * @param jws the parsed verified/authenticated JWS.\n     * @return any object to be used after inspecting the JWS, or {@code null} if no return value is necessary.\n     * @throws UnsupportedJwtException by default, expecting the subclass implementation to override as necessary.\n     */\n    public T onVerifiedContent(Jws<byte[]> jws) {\n        throw new UnsupportedJwtException(\"Unexpected content JWS.\");\n    }\n\n    /**\n     * Handles an encountered JWS message that has been cryptographically verified/authenticated and has a\n     * {@link Claims} payload.\n     *\n     * <p>The default implementation immediately throws an {@link UnsupportedJwtException}; it is expected that\n     * subclasses will override this method if the application needs to support this type of JWT.</p>\n     *\n     * @param jws the parsed signed (and verified) Claims JWS\n     * @return any object to be used after inspecting the JWS, or {@code null} if no return value is necessary.\n     * @throws UnsupportedJwtException by default, expecting the subclass implementation to override as necessary.\n     */\n    public T onVerifiedClaims(Jws<Claims> jws) {\n        throw new UnsupportedJwtException(\"Unexpected Claims JWS.\");\n    }\n\n    /**","sourceCodeStart":111,"sourceCodeEnd":147,"githubUrl":"https://github.com/jwtk/jjwt/blob/fb71496164c71442d08adec4571d9616ed5e1b8d/api/src/main/java/io/jsonwebtoken/SupportedJwtVisitor.java#L111-L147","documentation":"SupportedJwtVisitor.onVerifiedContent is the default callback for a JWS (cryptographically verified token) whose payload is arbitrary content (byte[], not Claims JSON). The base implementation throws UnsupportedJwtException because the library assumes a specific visitor subclass; applications handling raw-payload JWSs must override this method. It indicates the token type received does not match what the visitor is configured to handle.","triggerScenarios":"Parsing a signed compact token whose payload is not a Claims JSON object (e.g. arbitrary string/binary content) via a parser whose visitor does not override onVerifiedContent. E.g. calling parser.parse() on a JWS built with Jwts.builder().setContent(bytes, sigAlg, key).","commonSituations":"Exchanging opaque signed payloads between services; a developer expected Claims but the producer sent raw content; mixing parseClaimsJws with content-JWS tokens; generic token-handling middleware that lacks an onVerifiedContent override.","solutions":["Override onVerifiedContent in your SupportedJwtVisitor subclass to process Jws<byte[]> and return the desired value.","If the payload should be Claims, change the producer to use claim-based builder APIs (Jwts.builder().claims()...) so onVerifiedClaims is dispatched instead.","If content JWSs are not expected, reject the token and validate the producer/endpoint sending it.","Use the matching parse API (e.g. parseContentJws if available) so the intended callback is invoked."],"exampleFix":"// before\nSupportedJwtVisitor<MyType> visitor = new SupportedJwtVisitor<>() {}; // default throws\n// after\nSupportedJwtVisitor<MyType> visitor = new SupportedJwtVisitor<>() {\n    @Override\n    public MyType onVerifiedContent(Jws<byte[]> jws) {\n        byte[] payload = jws.getPayload();\n        return processSignedContent(payload);\n    }\n};","handlingStrategy":"try-catch","validationCode":"// Decode header before parsing to learn the payload kind\nString headerJson = new String(Base64.getUrlDecoder().decode(compact.split(\"\\\\.\")[0]));\nboolean isJwsWithClaims = headerJson.contains(\"\\\"JWT\\\"\"); // typ claim hint\nif (!isJwsWithClaims && !visitorSupportsContentJws) {\n    throw new IllegalArgumentException(\"Content JWS not supported by this handler\");\n}","typeGuard":"boolean isSignedContentJws(String token) {\n    String[] p = token.split(\"\\\\.\", -1);\n    return p.length == 3 && !p[2].isEmpty(); // signed (has signature), payload type confirmed at parse time\n}","tryCatchPattern":"try {\n    result = Jwts.parser().verifyWith(key).build().parse(token);\n} catch (UnsupportedJwtException e) {\n    log.warn(\"Received a content JWS the visitor does not handle\", e);\n    throw new SecurityException(\"Unsupported JWS payload type\", e);\n}","preventionTips":["Implement onVerifiedContent whenever your visitor may see non-Claims signed payloads","Agree on token types (typ header) between producers and consumers","Use the specific parse method (parseClaimsJws vs content parse) matching the expected payload","Unit-test the visitor against every token shape your system exchanges"],"tags":["java","jwt","jjwt","jws","unsupported-jwt"],"backgroundTag":"unsupported-operation","analyzedSha":"fb71496164c71442d08adec4571d9616ed5e1b8d","analyzedAt":"2026-09-09T00:33:09.982Z","contentChangedAt":"2026-09-09T00:33:09.982Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}