Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Security and hardening

Jwts.parserBuilder() no longer compiles after upgrading JJWT

ErrorCompile error on Jwts.parserBuilder() after a version bump

Short answer

JJWT 0.12.0 removed Jwts.parserBuilder() because Jwts.parser() now returns the builder itself. Replace the chain with Jwts.parser().verifyWith(key).build().parseSignedClaims(token).getPayload(), and declare all three JJWT artifacts on one version so parsing also works at runtime.

  • Applies to JJWT 0.12 and 0.13, Java 21, Spring Boot 3.5
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find out which JJWT version the build really resolves. Code written for 0.11 and a 0.12+ jar on the classpath is the usual mismatch.

    ./mvnw dependency:tree -Dincludes=io.jsonwebtoken
    # Gradle
    ./gradlew dependencies --configuration runtimeClasspath | grep jsonwebtoken
  2. 2Match what you see, then jump to its fix

    1. 1A compile error on parserBuilder() right after a version bumpThe method was removed in 0.12.0Fix
    2. 2Deprecation warnings or errors on parseClaimsJws, getBody, Keys.secretKeyForOld method names such as parseClaimsJws, getBody and setSigningKey are still in the codeFix
    3. 3Code compiles, but parsing fails at runtimeOnly the API artifact is on the classpathFix

What does the error look like?

  • Compile error on Jwts.parserBuilder() after a version bump
  • setSigningKey / parseClaimsJws / getBody shown as deprecated

Cause 1 of 3

The method was removed in 0.12.0

1Check

The 0.12.0 release is the project's first breaking change release, and its notes say parserBuilder() was removed as redundant.

grep -rn "parserBuilder" src/

2Fix

Call Jwts.parser() instead. It now returns a JwtParserBuilder, so set the key on it and then call build().

Claims claims = Jwts.parser()
    .verifyWith(secretKey)
    .build()
    .parseSignedClaims(token)
    .getPayload();

3Verify

Compile the project.

./mvnw -q compile

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 2 of 3

Old method names such as parseClaimsJws, getBody and setSigningKey are still in the code

1Check

Search for the 0.11 style calls. The 0.12.0 notes deprecate parseClaimsJws in favour of parseSignedClaims, and getBody in favour of getPayload.

grep -rnE "parseClaimsJws|getBody\(|secretKeyFor|setSigningKey" src/

2Fix

Use parseSignedClaims and getPayload. To create a new HMAC key use the algorithm's key builder instead of Keys.secretKeyFor.

SecretKey key = Jwts.SIG.HS256.key().build();

3Verify

Recompile and run the tests that parse a token.

./mvnw -q test

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 3 of 3

Only the API artifact is on the classpath

1Check

JJWT is split in three artifacts. jjwt-api is compile scope; jjwt-impl and a JSON module are needed at runtime.

grep -n "jjwt" pom.xml

2Fix

Declare all three, on the same version.

<dependency>
  <groupId>io.jsonwebtoken</groupId>
  <artifactId>jjwt-api</artifactId>
  <version>0.13.0</version>
</dependency>
<dependency>
  <groupId>io.jsonwebtoken</groupId>
  <artifactId>jjwt-impl</artifactId>
  <version>0.13.0</version>
  <scope>runtime</scope>
</dependency>
<dependency>
  <groupId>io.jsonwebtoken</groupId>
  <artifactId>jjwt-jackson</artifactId>
  <version>0.13.0</version>
  <scope>runtime</scope>
</dependency>

3Verify

Run the app and parse one token.

./mvnw -q test

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Pin all three JJWT artifacts to one version through a property or a BOM.
  • Read the project's CHANGELOG before bumping a security library.
  • Cover token parsing with a unit test so an upgrade breaks CI, not production.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.