{"record":{"id":"4af3ee2827c1159b","repo":"apache/dubbo","slug":"extension-instance-name-class-couldn-t","errorCode":null,"errorMessage":"Extension instance (name: {}, class: {}) couldn't be instantiated: {}","messagePattern":"Extension instance \\(name: (.+?), class: (.+?)\\) couldn't be instantiated: (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"dubbo-common/src/main/java/org/apache/dubbo/common/extension/ExtensionLoader.java","lineNumber":818,"sourceCode":"                                || ((ArrayUtils.isEmpty(wrapper.matches())\n                                                || ArrayUtils.contains(wrapper.matches(), name))\n                                        && !ArrayUtils.contains(wrapper.mismatches(), name));\n                        if (match) {\n                            instance = (T) wrapperClass.getConstructor(type).newInstance(instance);\n                            instance = postProcessBeforeInitialization(instance, name);\n                            injectExtension(instance);\n                            instance = postProcessAfterInitialization(instance, name);\n                        }\n                    }\n                }\n            }\n\n            // Warning: After an instance of Lifecycle is wrapped by cachedWrapperClasses, it may not still be Lifecycle\n            // instance, this application may not invoke the lifecycle.initialize hook.\n            initExtension(instance);\n            return instance;\n        } catch (Throwable t) {\n            throw new IllegalStateException(\n                    \"Extension instance (name: \" + name + \", class: \" + type + \") couldn't be instantiated: \"\n                            + t.getMessage(),\n                    t);\n        }\n    }\n\n    private Object createExtensionInstance(Class<?> type) throws ReflectiveOperationException {\n        return instantiationStrategy.instantiate(type);\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    private T postProcessBeforeInitialization(T instance, String name) throws Exception {\n        if (extensionPostProcessors != null) {\n            for (ExtensionPostProcessor processor : extensionPostProcessors) {\n                instance = (T) processor.postProcessBeforeInitialization(instance, name);\n            }\n        }\n        return instance;","sourceCodeStart":800,"sourceCodeEnd":836,"githubUrl":"https://github.com/apache/dubbo/blob/3a3043227f5571d25eb2889de5bca22f2914843b/dubbo-common/src/main/java/org/apache/dubbo/common/extension/ExtensionLoader.java#L800-L836","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the chained cause (getCause()) - it contains the actual reflective or initialization exception.","Ensure the extension class has a public no-arg constructor (Dubbo's instantiationStrategy requires it).","Check that any setter used for SPI injection does not throw; the setter receives injected extensions and must handle missing/optional deps gracefully.","If a wrapper class is involved, verify its single-argument constructor matching the SPI interface type does not throw.","Run with -Ddubbo.application.logger=slf4j and DEBUG on org.apache.dubbo.common.extension to trace which lifecycle/init step fails."],"exampleFix":"// before: extension class constructor throws\npublic class MyProtocol implements Protocol {\n    public MyProtocol() {\n        throw new NullPointerException(\"config not ready\");\n    }\n}\n// getExtension(\"myProtocol\") throws [141]\n\n// after: make construction safe, do heavy work in initialize()\npublic class MyProtocol implements Protocol, Lifecycle {\n    public MyProtocol() { } // no-arg, no side effects\n    public void initialize() throws IllegalStateException {\n        // validate config here; Dubbo calls this via initExtension\n    }\n}","handlingStrategy":"try-catch","validationCode":"// Validate the extension name is known before instantiating\nSet<String> supported = extensionDirector.getExtensionLoader(MySpi.class).getSupportedExtensions();\nif (!supported.contains(name)) {\n    throw new IllegalArgumentException(\"Unknown extension name: \" + name);\n}","typeGuard":null,"tryCatchPattern":"try {\n    T ext = loader.getExtension(name);\n} catch (IllegalStateException e) {\n    Throwable root = e.getCause() != null ? e.getCause() : e;\n    if (root instanceof ReflectiveOperationException) {\n        log.error(\"Constructor/instantiation failure for {}\", name, root);\n    }\n    throw e;\n}","preventionTips":["Ensure extension classes have public no-arg constructors.","Keep setter methods (used for SPI injection) side-effect-free or exception-safe.","Verify wrapper classes have a single-arg constructor taking the SPI interface type.","Unit-test each extension class in isolation before registering it."],"tags":["dubbo-spi","extension-instantiation","injection","extension-loader"],"backgroundTag":null,"analyzedSha":"3a3043227f5571d25eb2889de5bca22f2914843b","analyzedAt":"2026-08-14T00:43:19.853Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}