apache/pulsar · error · IllegalArgumentException

Failed to instantiate ${className}

Error message

Failed to instantiate ${className}

What it means

PulsarConfigurationLoader.create instantiates a configuration class reflectively via its no-arg constructor and then applies the properties. If instantiation fails (abstract class, no accessible no-arg constructor, or the constructor/field population throws InstantiationException, IllegalAccessException, NoSuchMethodException, or InvocationTargetException), it rethrows as this IllegalArgumentException with the class name.

Source

Thrown at pulsar-broker-common/src/main/java/org/apache/pulsar/common/configuration/PulsarConfigurationLoader.java:157

     *
     * @param properties The properties to populate the attributed from
     * @throws IOException
     * @throws IllegalArgumentException
     */
    @SuppressWarnings({ "rawtypes", "unchecked" })
    public static <T extends PulsarConfiguration> T create(Properties properties,
            Class<? extends PulsarConfiguration> clazz) throws IOException, IllegalArgumentException {
        requireNonNull(properties);
        // PIP-478: reject a stale, removed PIP-337 sslFactoryPlugin key rather than silently ignoring it.
        rejectRemovedPip337TlsFactoryKeys(properties);
        T configuration;
        try {
            configuration = (T) clazz.getDeclaredConstructor().newInstance();
            configuration.setProperties(properties);
            update((Map) properties, configuration);
        } catch (InstantiationException | IllegalAccessException
                | NoSuchMethodException | InvocationTargetException e) {
            throw new IllegalArgumentException("Failed to instantiate " + clazz.getName(), e);
        }
        return configuration;
    }

    /**
     * Validates {@link FieldContext} annotation on each field of the class element. If element is annotated required
     * and value of the element is null or number value is not in a provided (min,max) range then consider as incomplete
     * object and throws exception with incomplete parameters
     *
     * @param obj
     * @return
     * @throws IllegalArgumentException
     *             if object is field values are not completed according to {@link FieldContext} constraints.
     * @throws IllegalAccessException
     */
    public static boolean isComplete(Object obj) throws IllegalArgumentException {
        requireNonNull(obj);
        Field[] fields = obj.getClass().getDeclaredFields();

View on GitHub (pinned to 820761864e)

Solutions

1. Ensure the configuration class is concrete and has a public no-arg constructor
2. Inspect the cause ('Caused by') to see the exception thrown from the constructor if it's an InvocationTargetException
3. Verify you passed the correct concrete configuration class, not an interface or abstract base class
4. Remove initialization logic that can throw from the constructor; defer it to validation

Example fix

// before
public class MyConfig implements PulsarConfiguration {
  public MyConfig(String path) { load(path); }
}
// after
public class MyConfig implements PulsarConfiguration {
  public MyConfig() { }
}

Class<?> clazz = MyConfig.class;
boolean ok = !clazz.isInterface() && !java.lang.reflect.Modifier.isAbstract(clazz.getModifiers())
    && java.util.Arrays.stream(clazz.getConstructors())
        .anyMatch(c -> c.getParameterCount() == 0);
if (!ok) throw new IllegalStateException(clazz.getName() + " needs a public no-arg constructor");

try {
    T conf = PulsarConfigurationLoader.create(props, clazz);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Failed to instantiate")) {
        log.error("Config class {} cannot be constructed; check Caused by", clazz.getName(), e);
    }
    throw e;
}

When it happens

Trigger: Calling create(Class<? extends PulsarConfiguration>, Properties) with a class lacking a public no-arg constructor, an abstract/ interface type, or whose declared constructor throws (InvocationTargetException from an exception inside the constructor).

Common situations: Custom configuration class written without a no-arg constructor; passing the wrong class object (e.g. an interface); a constructor that performs validation or IO and throws; classpath/version mismatch where constructor signature changed.

Related errors

• User class must be concrete
• Failed to create instance for key reader class
• Exception caused while converting configuration: ${message}
• Failed to compute configuration overrides
• Could not instantiate <configKeyName> '<factoryClassName>'

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/9b4918a5c637c2ae. Report an issue: GitHub.