jwtk/jjwt · error · java.lang.IllegalArgumentException

Invalid ${getName()} ${param} value: ${rawValue}. ${e.getMes

Error message

Invalid ${getName()} ${param} value: ${rawValue}. ${e.getMessage()}

What it means

Generic validation guard in ParameterMap.apply: thrown when converting a raw (usually user/JSON-supplied) value into a typed JJWT parameter fails — param.applyFrom rejected the raw value, or the resulting idiomatic/canonical value was null. The message names the parameter map, the parameter, and the offending raw value (secret parameters are redacted).

Source

Thrown at impl/src/main/java/io/jsonwebtoken/impl/ParameterMap.java:193

        try {
            idiomaticValue = param.applyFrom(rawValue);
            Assert.notNull(idiomaticValue, "Parameter's resulting idiomaticValue cannot be null.");
            canonicalValue = param.applyTo(idiomaticValue);
            Assert.notNull(canonicalValue, "Parameter's resulting canonicalValue cannot be null.");
        } catch (Exception e) {
            StringBuilder sb = new StringBuilder(100);
            sb.append("Invalid ").append(getName()).append(" ").append(param).append(" value");
            if (param.isSecret()) {
                sb.append(": ").append(RedactedConfidentialValue.REDACTED_VALUE);
            } else if (!(rawValue instanceof byte[])) {
                // don't print raw byte array gibberish.  We can't base64[url] encode it either because that could
                // make the exception message confusing: the developer would see an encoded string and could think
                // that was the rawValue specified when it wasn't.
                sb.append(": ").append(Objects.nullSafeToString(rawValue));
            }
            sb.append(". ").append(e.getMessage());
            String msg = sb.toString();
            throw new IllegalArgumentException(msg, e);
        }
        this.idiomaticValues.put(id, idiomaticValue);
        return this.values.put(id, canonicalValue);
    }

    @Override
    public Object remove(Object key) {
        assertMutable();
        this.idiomaticValues.remove(key);
        return this.values.remove(key);
    }

    @Override
    public void putAll(Map<? extends String, ?> m) {
        if (m == null) {
            return;
        }
        for (Map.Entry<? extends String, ?> entry : m.entrySet()) {

View on GitHub (pinned to fb71496164)

Solutions

1. Read the embedded cause (e.getMessage()) to see which conversion failed (format, range, type) and correct the input value before passing it to the builder/put call
2. Ensure the value's type matches what the parameter expects (e.g. pass an Integer/Date/Key, not a String, where applicable)
3. If the value comes from external JSON/config, validate and normalize it (parse dates to java.util.Date, numbers to the expected type) before building the JWT/JWK

When it happens

Trigger: Thrown at impl/src/main/java/io/jsonwebtoken/impl/ParameterMap.java:193 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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