jwtk/jjwt · error · InvalidKeyException

${familyName} ${keyType} keys must be ECKey instances.

Error message

${familyName} ${keyType} keys must be ECKey instances.

What it means

Type guard in SignatureAlgorithm.assertValid: for elliptic-curve algorithms (ES256/ES384/ES512), the key must implement io.jsonwebtoken.ECKey (exposing ECParameterSpec) so the curve order can be size-checked. A PrivateKey of another type (e.g. RSAKey) or an EC PrivateKey that does not implement the ECKey interface is rejected with InvalidKeyException.

Source

Thrown at api/src/main/java/io/jsonwebtoken/SignatureAlgorithm.java:414

                if (encoded != null) {
                    Arrays.fill(encoded, (byte) 0);
                }
            }

        } else { //EC or RSA

            if (signing) {
                if (!(key instanceof PrivateKey)) {
                    String msg = familyName + " signing keys must be PrivateKey instances.";
                    throw new InvalidKeyException(msg);
                }
            }

            if (isEllipticCurve()) {

                if (!(key instanceof ECKey)) {
                    String msg = familyName + " " + keyType(signing) + " keys must be ECKey instances.";
                    throw new InvalidKeyException(msg);
                }

                ECKey ecKey = (ECKey) key;
                int size = ecKey.getParams().getOrder().bitLength();
                if (size < this.minKeyLength) {
                    String msg = "The " + keyType(signing) + " key's size (ECParameterSpec order) is " + size +
                            " bits which is not secure enough for the " + name() + " algorithm.  The JWT " +
                            "JWA Specification (RFC 7518, Section 3.4) states that keys used with " +
                            name() + " MUST have a size >= " + this.minKeyLength +
                            " bits.  Consider using the " + Keys.class.getName() + " class's " +
                            "'keyPairFor(SignatureAlgorithm." + name() + ")' method to create a key pair guaranteed " +
                            "to be secure enough for " + name() + ".  See " +
                            "https://tools.ietf.org/html/rfc7518#section-3.4 for more information.";
                    throw new WeakKeyException(msg);
                }

            } else { //RSA

View on GitHub (pinned to fb71496164)

Solutions

1. Use an EC key pair from Keys.keyPairFor(SignatureAlgorithm.ES256) — the returned keys implement ECKey.
2. If you hold a raw java.security.interfaces.ECPrivateKey, adapt or load it such that it implements io.jsonwebtoken.ECKey (e.g. via DefaultEcKey or a keystore path jjwt supports).
3. Verify you are not mixing families: RSA keys must go to RS*/PS* algorithms, EC keys to ES*.

When it happens

Trigger: Thrown at api/src/main/java/io/jsonwebtoken/SignatureAlgorithm.java:414 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/96d71c221c13ec0f. Report an issue: GitHub.