jwtk/jjwt · error · io.jsonwebtoken.security.MalformedKeySetException

Missing required keys parameter.

Error message

Missing required keys parameter.

What it means

Thrown by JwkSetConverter.applyFrom when the JWK Set JSON object lacks the mandatory keys member. RFC 7517 §5 defines keys as the one required member of a JWK Set, so its absence makes the input not a valid JWK Set and conversion fails with MalformedKeySetException.

Source

Thrown at impl/src/main/java/io/jsonwebtoken/impl/security/JwkSetConverter.java:87

    }

    @Override
    public JwkSet applyFrom(Object o) {
        Assert.notNull(o, "Value cannot be null.");
        if (o instanceof JwkSet) {
            return (JwkSet) o;
        }
        if (!(o instanceof Map)) {
            String msg = "Value must be a Map<String,?> (JSON Object). Type found: " + o.getClass().getName() + ".";
            throw new IllegalArgumentException(msg);
        }
        final Map<?, ?> m = Collections.immutable((Map<?, ?>) o);

        // mandatory for all JWK Sets: https://datatracker.ietf.org/doc/html/rfc7517#section-5
        // no need for builder parameter type conversion overhead if this isn't present:
        if (Collections.isEmpty(m) || !m.containsKey(PARAM.getId())) {
            String msg = "Missing required " + PARAM + " parameter.";
            throw new MalformedKeySetException(msg);
        }
        Object val = m.get(PARAM.getId());
        if (val == null) {
            String msg = "JWK Set " + PARAM + " value cannot be null.";
            throw new MalformedKeySetException(msg);
        }
        if (!(val instanceof Collection)) {
            String msg = "JWK Set " + PARAM + " value must be a Collection (JSON Array). Type found: " +
                    val.getClass().getName();
            throw new MalformedKeySetException(msg);
        }
        int size = Collections.size((Collection<?>) val);
        if (size == 0) {
            String msg = "JWK Set " + PARAM + " collection cannot be empty.";
            throw new MalformedKeySetException(msg);
        }

        // Copy values so we don't mutate the original input

View on GitHub (pinned to fb71496164)

Solutions

1. Add the required "keys" array to the JWK Set JSON
2. Verify the field is spelled exactly "keys"
3. Confirm you fetched the correct JWKS endpoint content

Example fix

// before
{"x5u":"https://example.com/cert"}
// after
{"keys":[{"kty":"RSA","n":"...","e":"AQAB"}]}

if (m == null || !m.containsKey("keys")) { throw new IllegalArgumentException("JWKS document must contain a 'keys' member"); }

boolean isWellFormedJwks(Object o) { return o instanceof Map<?,?> m && m.containsKey("keys"); }

try { JwkSet s = Jwks.setBuilder().build(); } catch (MalformedKeySetException e) { log.error("JWKS missing keys: {}", e.getMessage()); }

When it happens

Trigger: Parsing a JWKS document JSON object that has no "keys" member, e.g. {"x5u":"..."} or an empty object.

Common situations: IdP metadata endpoints returning objects without keys; wrong field name like "key" or "jwks" used instead of "keys"; cached/stripped responses.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• JWK is missing required kty parameter.
• JWK Set keys value cannot be null.
• JWK Set keys collection cannot be empty.
• JWK kty value cannot be null.
• JWK kty value cannot be empty.

AI-assisted analysis of jwtk/jjwt@fb71496164 (2026-09-09). Data as JSON: /api/errors/baf1db58d7c8671e. Report an issue: GitHub.