jwtk/jjwt · error · IllegalArgumentException

Value cannot be represented as a java.lang.Integer.

Error message

Value cannot be represented as a java.lang.Integer.

What it means

PositiveIntegerConverter.applyFrom converts an input object to an Integer by first attempting native conversion and falling back to Integer.parseInt(String.valueOf(o)). If that parse fails with NumberFormatException, the value cannot be represented as an Integer and this IllegalArgumentException is thrown (with the NumberFormatException as cause).

Source

Thrown at impl/src/main/java/io/jsonwebtoken/impl/lang/PositiveIntegerConverter.java:46

        return integer;
    }

    @Override
    public Integer applyFrom(Object o) {
        Assert.notNull(o, "Argument cannot be null.");
        int i;
        if (o instanceof Byte || o instanceof Short || o instanceof Integer || o instanceof AtomicInteger) {
            i = ((Number) o).intValue();
        } else {  // could be Long, AtomicLong, Float, Decimal, BigInteger, BigDecimal, String, etc., all of which
            // may not be accurately converted into an Integer, either due to overflow or fractional values.  The
            // easiest way to account for all of them is to parse the string value as an int instead of testing all
            // the types:
            String sval = String.valueOf(o);
            try {
                i = Integer.parseInt(sval);
            } catch (NumberFormatException e) {
                String msg = "Value cannot be represented as a java.lang.Integer.";
                throw new IllegalArgumentException(msg, e);
            }
        }
        if (i <= 0) {
            String msg = "Value must be a positive integer.";
            throw new IllegalArgumentException(msg);
        }
        return i;
    }
}

View on GitHub (pinned to fb71496164)

Solutions

1. Supply a genuine Integer/int value instead of a string or floating-point number.
2. If the value is a numeric string, ensure it has no decimals, signs beyond '-', or whitespace before conversion.
3. Pre-parse with Integer.parseInt yourself inside try/catch to give a clearer error.

Example fix

// before
jwtBuilder.claim("rate", "1.5");
// after
jwtBuilder.claim("rate", 2);

Integer asPositiveInt(Object o) {
    if (o instanceof Integer i) return i;
    if (o instanceof Number n && n.intValue() == n.doubleValue()) return n.intValue();
    return null; // not representable as an Integer
}

boolean isIntegralValue(Object o) {
    return o instanceof Integer
        || (o instanceof Number n && n.doubleValue() == n.intValue());
}

try {
    converter.applyFrom(value);
} catch (IllegalArgumentException e) {
    if (e.getCause() instanceof NumberFormatException) {
        // value not parseable as an integer
    }
    throw e;
}

When it happens

Trigger: Passing a non-integer string like "abc", "1.5", or an arbitrary object whose toString() is not a valid integer to a converter/claim that expects a positive integer value.

Common situations: Setting claims such as 'typ' header params or payload fields expecting integer counts with decimal or textual values; JSON values parsed as Double (1.0) being converted; copying claims from loosely typed maps.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• ${message}
• Claim '' value is too large or too small to be represented a
• Cannot convert existing claim value of type '%s' to desired
• String value is not a JWT NumericDate, nor is it ISO-8601-fo
• Value must be a positive integer.

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