{"record":{"id":"2072e43190004069","repo":"jwtk/jjwt","slug":"requiredmsg","errorCode":null,"errorMessage":"${requiredMsg}","messagePattern":"\\$\\{requiredMsg\\}","errorType":"validation","errorClass":"io.jsonwebtoken.MalformedJwtException","httpStatus":null,"severity":"error","filePath":"impl/src/main/java/io/jsonwebtoken/impl/IdLocator.java","lineNumber":54,"sourceCode":"    private final String requiredMsg;\n\n    public IdLocator(Parameter<String> param, Registry<String, R> registry, String algType, String behavior, String requiredExceptionMessage) {\n        this.param = Assert.notNull(param, \"Header param cannot be null.\");\n        this.registry = Assert.notNull(registry, \"Registry cannot be null.\");\n        this.algType = Assert.hasText(algType, \"algType cannot be null or empty.\");\n        this.behavior = Assert.hasText(behavior, \"behavior cannot be null or empty.\");\n        this.requiredMsg = Strings.clean(requiredExceptionMessage);\n    }\n\n    @Override\n    public R locate(Header header) {\n\n        Object val = header.get(this.param.getId());\n        String id = val != null ? val.toString() : null;\n\n        if (!Strings.hasText(id)) {\n            if (this.requiredMsg != null) { // a msg was provided, so the value is required:\n                throw new MalformedJwtException(requiredMsg);\n            }\n            return null; // otherwise header value not required, so short circuit\n        }\n\n        try {\n            return registry.forKey(id);\n        } catch (Exception e) {\n            StringBuilder sb = new StringBuilder(\"Unsupported \")\n                    .append(DefaultHeader.nameOf(header))\n                    .append(\" \")\n                    .append(this.param)\n                    .append(\" value '\").append(id).append(\"'\");\n            if (this.registry.isEmpty()) {\n                sb.append(\": \")\n                        .append(this.behavior)\n                        .append(\" is disabled (no \")\n                        .append(this.algType)\n                        .append(\" algorithms have been configured)\");","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/jwtk/jjwt/blob/fb71496164c71442d08adec4571d9616ed5e1b8d/impl/src/main/java/io/jsonwebtoken/impl/IdLocator.java#L36-L72","documentation":"IdLocator reads an id value (e.g. kid header parameter) from the JWT and looks it up in a registry. When the value is missing or blank and a required message was supplied, it throws MalformedJwtException with that message. This means the token's header lacks a required identifier (such as kid) that key lookup depends on.","triggerScenarios":"Parsing a JWT whose header omits the required id parameter (commonly 'kid') while the parser was built with a required key locator/registry (e.g. verifyWithKeyLocator or header-value-required configuration).","commonSituations":"Tokens issued by a provider that doesn't set kid being parsed by a consumer configured to require it; a token signed/serialized by different tooling that strips custom headers; rotation setups where new tokens must carry kid but old ones don't.","solutions":["Fix token issuance so the required header id (e.g. kid) is always included","If the id is genuinely optional, build the locator without the required message so missing values return null","Catch MalformedJwtException and reject/refresh the token with a clear client-side error"],"exampleFix":"// before (token header)\n{\"alg\":\"HS256\"}            // missing kid\n// after\n{\"alg\":\"HS256\",\"kid\":\"key-2024-01\"}","handlingStrategy":"try-catch","validationCode":"String kid = parsed.getHeader(\"kid\");\nif (kid == null || kid.isBlank()) throw new MalformedJwtException(\"token missing kid\");","typeGuard":null,"tryCatchPattern":"try {\n    Jws<Claims> jws = parser.parseClaimsJws(token);\n} catch (MalformedJwtException e) {\n    respond(400, \"Token is missing a required header identifier\");\n}","preventionTips":["Ensure the token issuer always sets kid when key lookup is id-based","Decide explicitly whether the header id is required and configure the locator accordingly","Monitor MalformedJwtException rates to detect issuer-side regressions"],"tags":["jwt","malformed-token","header-validation"],"backgroundTag":"missing-required-argument","analyzedSha":"fb71496164c71442d08adec4571d9616ed5e1b8d","analyzedAt":"2026-09-09T00:33:09.982Z","contentChangedAt":"2026-09-09T00:33:09.982Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}