apache/dubbo · critical · IllegalStateException

Extension instance (name: {}, class: {}) couldn't be instant

Error message

Extension instance (name: {}, class: {}) couldn't be instantiated: {}

What it means

Thrown by createExtension(String name, boolean wrap) when any Throwable escapes the instantiation, post-processing, dependency injection (injectExtension), wrapper application, or lifecycle initialization (initExtension) of a named extension. It is a catch-all that wraps the original failure with the extension name and SPI interface type, preserving the cause. The error indicates the extension class was found and resolved but could not be brought to a usable instance.

Source

Thrown at dubbo-common/src/main/java/org/apache/dubbo/common/extension/ExtensionLoader.java:818

                                || ((ArrayUtils.isEmpty(wrapper.matches())
                                                || ArrayUtils.contains(wrapper.matches(), name))
                                        && !ArrayUtils.contains(wrapper.mismatches(), name));
                        if (match) {
                            instance = (T) wrapperClass.getConstructor(type).newInstance(instance);
                            instance = postProcessBeforeInitialization(instance, name);
                            injectExtension(instance);
                            instance = postProcessAfterInitialization(instance, name);
                        }
                    }
                }
            }

            // Warning: After an instance of Lifecycle is wrapped by cachedWrapperClasses, it may not still be Lifecycle
            // instance, this application may not invoke the lifecycle.initialize hook.
            initExtension(instance);
            return instance;
        } catch (Throwable t) {
            throw new IllegalStateException(
                    "Extension instance (name: " + name + ", class: " + type + ") couldn't be instantiated: "
                            + t.getMessage(),
                    t);
        }
    }

    private Object createExtensionInstance(Class<?> type) throws ReflectiveOperationException {
        return instantiationStrategy.instantiate(type);
    }

    @SuppressWarnings("unchecked")
    private T postProcessBeforeInitialization(T instance, String name) throws Exception {
        if (extensionPostProcessors != null) {
            for (ExtensionPostProcessor processor : extensionPostProcessors) {
                instance = (T) processor.postProcessBeforeInitialization(instance, name);
            }
        }
        return instance;

View on GitHub (pinned to 3a3043227f)

Solutions

1. Read the chained cause (getCause()) - it contains the actual reflective or initialization exception.
2. Ensure the extension class has a public no-arg constructor (Dubbo's instantiationStrategy requires it).
3. Check that any setter used for SPI injection does not throw; the setter receives injected extensions and must handle missing/optional deps gracefully.
4. If a wrapper class is involved, verify its single-argument constructor matching the SPI interface type does not throw.
5. Run with -Ddubbo.application.logger=slf4j and DEBUG on org.apache.dubbo.common.extension to trace which lifecycle/init step fails.

Example fix

// before: extension class constructor throws
public class MyProtocol implements Protocol {
    public MyProtocol() {
        throw new NullPointerException("config not ready");
    }
}
// getExtension("myProtocol") throws [141]

// after: make construction safe, do heavy work in initialize()
public class MyProtocol implements Protocol, Lifecycle {
    public MyProtocol() { } // no-arg, no side effects
    public void initialize() throws IllegalStateException {
        // validate config here; Dubbo calls this via initExtension
    }
}

// Validate the extension name is known before instantiating
Set<String> supported = extensionDirector.getExtensionLoader(MySpi.class).getSupportedExtensions();
if (!supported.contains(name)) {
    throw new IllegalArgumentException("Unknown extension name: " + name);
}

try {
    T ext = loader.getExtension(name);
} catch (IllegalStateException e) {
    Throwable root = e.getCause() != null ? e.getCause() : e;
    if (root instanceof ReflectiveOperationException) {
        log.error("Constructor/instantiation failure for {}", name, root);
    }
    throw e;
}

When it happens

Trigger: Calling getExtension(name), getDefaultExtension(), or getActivateExtension() for a name whose class is registered but fails during: ReflectiveOperationException from createExtensionInstance (no accessible constructor), injectExtension invoking a setter that throws, postProcessBeforeInitialization/postProcessAfterInitialization throwing, wrapper constructor failing, or initExtension throwing on a Lifecycle instance.

Common situations: A setter method annotated for SPI injection receives a value whose own creation fails; the extension class has no public no-arg constructor; a wrapper class constructor throws when wrapping the instance; an @Activate extension's initialize() lifecycle hook fails on missing config; classpath conflicts where a different version of the extension class has an incompatible constructor.

Related errors

• Extension type == null
• Exception occurred when loading extension class (interface:
• More than 1 default extension name on extension {}: {}
• Error occurred when loading extension class (interface: {},
• No such extension name for the class {} in the config {}

AI-assisted analysis of apache/dubbo@3a3043227f (2026-08-14). Data as JSON: /api/errors/4af3ee2827c1159b. Report an issue: GitHub.