jwtk/jjwt · error · InstantiationException

Unable to instantiate class [${clazzName}]

Error message

Unable to instantiate class [${clazzName}]

What it means

InstantiationException thrown by io.jsonwebtoken.lang.Classes.newInstance(Class) when clazz.newInstance() fails for any reason (no public no-arg constructor, abstract class/interface, constructor throws, or access restrictions). The original exception is attached as the cause.

Source

Thrown at api/src/main/java/io/jsonwebtoken/lang/Classes.java:221

        return (T) newInstance(forName(fqcn), args);
    }

    /**
     * Creates a new instance of the specified {@code clazz} via {@code clazz.newInstance()}.
     *
     * @param clazz the class to invoke
     * @param <T>   the type of the object created
     * @return the newly created object
     */
    public static <T> T newInstance(Class<T> clazz) {
        if (clazz == null) {
            String msg = "Class method parameter cannot be null.";
            throw new IllegalArgumentException(msg);
        }
        try {
            return clazz.newInstance();
        } catch (Exception e) {
            throw new InstantiationException("Unable to instantiate class [" + clazz.getName() + "]", e);
        }
    }

    /**
     * Returns a new instance of the specified {@code clazz}, invoking the associated constructor with the specified
     * {@code args} arguments.
     *
     * @param clazz the class to invoke
     * @param args  the arguments matching an associated class constructor
     * @param <T>   the type of the created object
     * @return the newly created object
     */
    public static <T> T newInstance(Class<T> clazz, Object... args) {
        Class<?>[] argTypes = new Class[args.length];
        for (int i = 0; i < args.length; i++) {
            argTypes[i] = args[i].getClass();
        }
        Constructor<T> ctor = getConstructor(clazz, argTypes);

View on GitHub (pinned to fb71496164)

Solutions

1. Ensure the target class is public, concrete (not abstract/interface), and has a public no-arg constructor
2. Inspect the cause exception (InstantiationException/InvocationTargetException) for the real failure
3. If the constructor throws, fix the throwing initialization code inside that constructor
4. Make the class static if it is a non-static inner class, or add an explicit public no-arg constructor

Example fix

// before
public class MySigner implements Signer { // interface instantiation fails if MySigner were abstract
    public MySigner(String key) { ... } // no no-arg ctor
}
// after
public class MySigner implements Signer {
    public MySigner() { ... } // public no-arg constructor
}

Class<?> c = ...;
if (c.isInterface() || Modifier.isAbstract(c.getModifiers())) {
    throw new IllegalArgumentException(c + " is not instantiable");
}
try { c.getDeclaredConstructor(); } catch (NoSuchMethodException e) {
    throw new IllegalArgumentException(c + " lacks a public no-arg constructor");
}

try {
    return Classes.newInstance(clazz);
} catch (InstantiationException e) {
    LOG.error("Cannot instantiate " + clazz + ": " + e.getCause(), e);
    throw e;
}

When it happens

Trigger: Calling Classes.newInstance on an interface or abstract class; the class has no public no-arg constructor; the no-arg constructor itself throws; the class is not accessible from the caller's classloader/package.

Common situations: Configuring a custom class in jjwt config that is an interface or lacks a no-arg constructor; inner classes without static modifier (no implicit no-arg ctor on instances); JDK module/access restrictions (e.g. JDK 9+ strong encapsulation) blocking instantiation.

Related errors

• Unable to instantiate instance with constructor [${ctor}]
• Unable to load class named [${fqcn}] from the thread context
• Class method parameter cannot be null.
• Unable to invoke class method ${fqcn}#${methodName}. Ensure
• Unable to invoke class method ${clazzName}#${methodName}. En

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