jwtk/jjwt · error · IllegalArgumentException

Unrecognized

Error message

Unrecognized ${qualifiedKeyName}: ${key}

What it means

DefaultRegistry.forKey looks up a registry entry by key and throws IllegalArgumentException ('Unrecognized <qualifiedKeyName>: <key>') when the key is absent. Registries in JJWT hold known instances keyed by identifiers, such as JWA algorithms or compression codecs.

Solutions

  1. Verify the exact key string (case, spelling, no whitespace) against the registry's documented ids.
  2. Check registry contents/containsKey (get returns null) before calling forKey.
  3. Ensure the corresponding provider/module is on the classpath if the id should exist (e.g. optional crypto providers).

Example fix

// before
SignatureAlgorithm alg = registry.forKey(config.getAlg()); // typo 'HS356'
// after
String id = config.getAlg();
if (registry.forKey == null || !SignatureAlgorithm.NAMES.contains(id)) {
    throw new IllegalArgumentException("Unknown algorithm: " + id);
}
Defensive patterns

Strategy: validation

Validate before calling

V val = registry.get(key); // or containsKey if available
if (val == null) {
    throw new IllegalArgumentException("Unsupported id: " + key);
}

Try / catch

try {
    V v = registry.forKey(id);
} catch (IllegalArgumentException e) {
    // fall back to default id or surface a clear config error
}

Prevention

When it happens

Trigger: Passing an algorithm/codec id string not present in the registry, e.g. looking up 'HS512' in a registry that excludes it, a typo like 'HS356', or an algorithm disabled at runtime (weak-key checks removed it).

Common situations: Configuring a JWT parser/signer with an algorithm name from properties that contains whitespace or wrong case; referencing an algorithm the installed key doesn't support; version changes where a registry no longer contains an id.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

Appendix: source

Thrown at impl/src/main/java/io/jsonwebtoken/impl/lang/DefaultRegistry.java:60

    public DefaultRegistry(String name, String keyName, Collection<? extends V> values, Function<V, K> keyFn) {
        super(toMap(values, keyFn));
        name = Assert.hasText(Strings.clean(name), "name cannot be null or empty.");
        keyName = Assert.hasText(Strings.clean(keyName), "keyName cannot be null or empty.");
        this.qualifiedKeyName = name + " " + keyName;
    }

    @Override
    public V apply(K k) {
        return get(k);
    }

    @Override
    public V forKey(K key) {
        V value = get(key);
        if (value == null) {
            String msg = "Unrecognized " + this.qualifiedKeyName + ": " + key;
            throw new IllegalArgumentException(msg);
        }
        return value;
    }

    static <T> T immutable() {
        throw new UnsupportedOperationException("Registries are immutable and cannot be modified.");
    }

    @Override
    public V put(K key, V value) {
        return immutable();
    }

    @Override
    public V remove(Object key) {
        return immutable();
    }

View on GitHub (pinned to fb71496164)