jwtk/jjwt · error · UnsupportedKeyException

noFamily(key, kty)

Error message

noFamily(key, kty)

What it means

Thrown as UnsupportedKeyException when DispatchingJwkFactory.newContext cannot find any registered FamilyJwkFactory whose supports() matches the given Key or source JWK map. In other words, neither the key's Java type nor the JWK 'kty' value maps to a key family (RSA, EC, octet, OKP) the library knows.

Source

Thrown at impl/src/main/java/io/jsonwebtoken/impl/security/DispatchingJwkFactory.java:71

        this.factories = new ArrayList<>(factories.size());
        for (FamilyJwkFactory<?, ?> factory : factories) {
            Assert.hasText(factory.getId(), "FamilyJwkFactory.getFactoryId() cannot return null or empty.");
            this.factories.add((FamilyJwkFactory<Key, ?>) factory);
        }
    }

    @Override
    public JwkContext<Key> newContext(JwkContext<?> src, Key key) {
        Assert.notNull(src, "JwkContext cannot be null.");
        String kty = src.getType();
        assertKeyOrKeyType(key, kty);
        for (FamilyJwkFactory<Key, ?> factory : this.factories) {
            if (factory.supports(key) || factory.supports(src)) {
                JwkContext<Key> ctx = factory.newContext(src, key);
                return Assert.notNull(ctx, "FamilyJwkFactory implementation cannot return null JwkContexts.");
            }
        }
        throw noFamily(key, kty);
    }

    private static void assertKeyOrKeyType(Key key, String kty) {
        if (key == null && !Strings.hasText(kty)) {
            String msg = "Either a Key instance or a " + AbstractJwk.KTY + " value is required to create a JWK.";
            throw new InvalidKeyException(msg);
        }
    }

    @Override
    public Jwk<Key> createJwk(JwkContext<Key> ctx) {

        Assert.notNull(ctx, "JwkContext cannot be null.");

        final Key key = ctx.getKey();
        final String kty = Strings.clean(ctx.getType());
        assertKeyOrKeyType(key, kty);

View on GitHub (pinned to fb71496164)

Solutions

1. Correct the 'kty' value to a standard one: RSA, EC, oct, or OKP (exact, case-sensitive).
2. Use a supported Key type: RSAPublicKey, RSAPrivateKey, ECPublicKey, ECPrivateKey, or SecretKey.
3. Register additional family factories if supporting a custom key type is required (extend FamilyJwkFactory and configure the JwkFactory).
4. Catch UnsupportedKeyException during JWK set import and skip/log the offending entry.

Example fix

// before
{ "kty": "rsa", "n": "...", "e": "AQAB" }   // lowercase kty unsupported
// after
{ "kty": "RSA", "n": "...", "e": "AQAB" }

// validate kty before importing a JWK
String kty = (String) jwkMap.get("kty");
if (!Set.of("RSA","EC","oct","OKP").contains(kty))
    throw new InvalidJwkException("Unsupported kty: " + kty);

boolean knownKty = Set.of("RSA","EC","oct","OKP").contains(jwkMap.get("kty"));

try {
    return Jwts.SIG.parser().parse(jwkJson);
} catch (UnsupportedKeyException e) {
    log.warn("Skipping JWK with unsupported family", e);
    return null;
}

When it happens

Trigger: Creating a JWK context from a Key of unsupported type (e.g. DSA) or from a JWK map whose 'kty' is unrecognized (typo like 'rsa ' or custom values like 'RSA-PSS'), via JwkBuilder or Jwk parsing.

Common situations: Importing third-party JWK Sets with non-standard kty values; hand-editing JWK JSON; passing keys from custom crypto providers; case mistakes in kty (JWK kty values are case-sensitive).

Related errors

• unsupportedKey(key, e)
• Unrecognized JWA EC curve id '${jwaCurveId}'
• JWK is missing required kty parameter.
• JWK kty value cannot be null.
• JWK kty value must be a String. Type found: ${type}

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