jwtk/jjwt · error · java.lang.IllegalArgumentException

JWA Base64urlUInt values MUST be >= 0 (non-negative) per the

Error message

JWA Base64urlUInt values MUST be >= 0 (non-negative) per the 'Base64urlUInt' definition in [JWA RFC 7518, Section 2](https://www.rfc-editor.org/rfc/rfc7518.html#section-2)

What it means

BigIntegerUBytesConverter converts a BigInteger into the minimal unsigned byte array used by JWA (RFC 7518) for values like EC coordinates and 'kid'-related unsigned integers. JWA's Base64urlUInt definition requires the integer be non-negative, so applyTo explicitly rejects negative BigIntegers with an IllegalArgumentException. Negative numbers have no valid unsigned big-endian JWA representation.

Source

Thrown at impl/src/main/java/io/jsonwebtoken/impl/lang/BigIntegerUBytesConverter.java:32

 * limitations under the License.
 */
package io.jsonwebtoken.impl.lang;

import io.jsonwebtoken.lang.Assert;

import java.math.BigInteger;

public class BigIntegerUBytesConverter implements Converter<BigInteger, byte[]> {

    private static final String NEGATIVE_MSG =
        "JWA Base64urlUInt values MUST be >= 0 (non-negative) per the 'Base64urlUInt' definition in " +
            "[JWA RFC 7518, Section 2](https://www.rfc-editor.org/rfc/rfc7518.html#section-2)";

    @Override
    public byte[] applyTo(BigInteger bigInt) {
        Assert.notNull(bigInt, "BigInteger argument cannot be null.");
        if (BigInteger.ZERO.compareTo(bigInt) > 0) {
            throw new IllegalArgumentException(NEGATIVE_MSG);
        }

        final int bitLen = bigInt.bitLength();
        final byte[] bytes = bigInt.toByteArray();
        // Determine minimal number of bytes necessary to represent an unsigned byte array.
        // It must be 1 or more because zero still requires one byte
        final int unsignedByteLen = Math.max(1, Bytes.length(bitLen)); // always need at least one byte

        if (bytes.length == unsignedByteLen) { // already in the form we need
            return bytes;
        }
        //otherwise, we need to strip the sign byte (start copying at index 1 instead of 0):
        byte[] ubytes = new byte[unsignedByteLen];
        System.arraycopy(bytes, 1, ubytes, 0, unsignedByteLen);
        return ubytes;
    }

    @Override

View on GitHub (pinned to fb71496164)

Solutions

1. Ensure the BigInteger is non-negative before conversion: if (v.signum() < 0) v = v.add(modulus) (two's complement wrap into range) or fix the upstream computation.
2. Use BigInteger(1, signedBytes) with an explicit positive sign when constructing from raw bytes instead of new BigInteger(byte[]).
3. If the value is genuinely negative, it is not valid JWA data - regenerate the key material or signature.

Example fix

// before
BigInteger r = new BigInteger(signatureBytes); // may be negative
byte[] encoded = converter.applyTo(r);
// after
BigInteger r = new BigInteger(1, signatureBytes); // always non-negative
if (r.signum() < 0) { /* invalid key material - handle */ }
byte[] encoded = converter.applyTo(r);

if (value == null || value.signum() < 0) {
    throw new IllegalArgumentException("JWA Base64urlUInt value must be non-negative: " + value);
}

try {
    byte[] encoded = converter.applyTo(bigInt);
} catch (IllegalArgumentException e) {
    // handle negative/invalid BigInteger
}

When it happens

Trigger: Calling applyTo (directly or via JWT header/claim serialization) with a negative BigInteger, e.g. passing a negative ECDSA signature component (r or s), a negative x/y coordinate, or computing a value via modular arithmetic that wrapped negative.

Common situations: Hand-rolling ECDSA signature r/s values and accidentally producing negatives; decoding a byte array with sign-preserving BigInteger(byte[]) on data whose high bit is set; copying key material from a library that encodes values as signed.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Invalid Base64Url <name>: <value>
• Unable to ${codecName}-decode ${name}: ${t.getMessage()}
• Unexpected unsecured Claims JWT.
• Unexpected content JWS.
• Unexpected Claims JWS.

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