{"record":{"id":"1bc85f2a102b8182","repo":"jwtk/jjwt","slug":"getname-instance-is-immutable-and-may-not-be","errorCode":null,"errorMessage":"${getName()} instance is immutable and may not be modified.","messagePattern":"(.+?) instance is immutable and may not be modified\\.","errorType":"exception","errorClass":"java.lang.UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"impl/src/main/java/io/jsonwebtoken/impl/ParameterMap.java","lineNumber":80,"sourceCode":"    }\n\n    public ParameterMap(Registry<String, ? extends Parameter<?>> registry, Map<String, ?> values, boolean mutable) {\n        Assert.notNull(registry, \"Parameter registry cannot be null.\");\n        Assert.notEmpty(registry.values(), \"Parameter registry cannot be empty.\");\n        this.PARAMS = registry;\n        this.values = new LinkedHashMap<>();\n        this.idiomaticValues = new LinkedHashMap<>();\n        if (!Collections.isEmpty(values)) {\n            putAll(values);\n        }\n        this.mutable = mutable;\n        this.initialized = true;\n    }\n\n    private void assertMutable() {\n        if (initialized && !mutable) {\n            String msg = getName() + \" instance is immutable and may not be modified.\";\n            throw new UnsupportedOperationException(msg);\n        }\n    }\n\n    protected ParameterMap replace(Parameter<?> param) {\n        Registry<String, ? extends Parameter<?>> registry = Parameters.replace(this.PARAMS, param);\n        return new ParameterMap(registry, this, this.mutable);\n    }\n\n    @Override\n    public String getName() {\n        return \"Map\";\n    }\n\n    @Override\n    public <T> T get(Parameter<T> param) {\n        Assert.notNull(param, \"Parameter cannot be null.\");\n        final String id = Assert.hasText(param.getId(), \"Parameter id cannot be null or empty.\");\n        Object value = idiomaticValues.get(id);","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/jwtk/jjwt/blob/fb71496164c71442d08adec4571d9616ed5e1b8d/impl/src/main/java/io/jsonwebtoken/impl/ParameterMap.java#L62-L98","documentation":"ParameterMap (used for JWT/Claims/Jws header and claims collections) becomes immutable once finalized/initialized; afterwards any mutating call (put, remove, clear) is rejected with UnsupportedOperationException. The library protects header/claims instances handed to the user so parsed tokens cannot be modified in place.","triggerScenarios":"Calling put/remove/clear on a Jws.getHeader(), Claims instance obtained from a parsed token, or any ParameterMap after it has been initialized as immutable (e.g. the claims returned by parseClaimsJws).","commonSituations":"Trying to add a claim to a parsed token's Claims before re-signing; mutating header maps returned from Jws; building code that assumes mutable Maps because Claims extends Map.","solutions":["Create a new mutable map: new HashMap<>(claims), mutate the copy, and build a new JWT with Jwts.builder().setClaims(copy)","Use Jwts.builder() to construct modified tokens instead of mutating parsed ones","If constructing your own ParameterMap, keep it mutable (mutable=true) until you intentionally finalize it"],"exampleFix":"// before\nClaims claims = Jwts.parser().verifyWith(key).parseClaimsJws(jwt).getBody();\nclaims.put(\"role\", \"admin\"); // UnsupportedOperationException\n// after\nClaims claims = Jwts.parser().verifyWith(key).parseClaimsJws(jwt).getBody();\nMap<String, Object> updated = new HashMap<>(claims);\nupdated.put(\"role\", \"admin\");\nString newJwt = Jwts.builder().setClaims(updated).signWith(key).compact();","handlingStrategy":"type-guard","validationCode":"// copy before mutating\nMap<String, Object> editable = new HashMap<>(jws.getHeader());\neditable.put(\"typ\", \"JWT\");","typeGuard":"boolean isMutable(ParameterMap map) {\n    try { map.isEmpty(); return true; } catch (UnsupportedOperationException e) { return false; }\n}","tryCatchPattern":"try {\n    claims.put(\"role\", \"admin\");\n} catch (UnsupportedOperationException e) {\n    claims = Jwts.claims(new HashMap<>(claims)); // rebuild mutable instance\n}","preventionTips":["Treat parsed header/Claims instances as read-only views","Always copy into a HashMap before modifying claims","Rebuild tokens with Jwts.builder() rather than mutating parsed ones"],"tags":["jwt","immutability","unsupported-operation"],"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"}