{"record":{"id":"3e1c272977dc6c2f","repo":"apache/dubbo","slug":"can-t-create-adaptive-extension-cause","errorCode":null,"errorMessage":"Can't create adaptive extension {}, cause: {}","messagePattern":"Can't create adaptive extension (.+?), cause: (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"dubbo-common/src/main/java/org/apache/dubbo/common/extension/ExtensionLoader.java","lineNumber":1444,"sourceCode":"\n        String name = clazz.getSimpleName();\n        if (name.endsWith(type.getSimpleName())) {\n            name = name.substring(0, name.length() - type.getSimpleName().length());\n        }\n        return name.toLowerCase();\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    private T createAdaptiveExtension() {\n        try {\n            T instance = (T) getAdaptiveExtensionClass().newInstance();\n            instance = postProcessBeforeInitialization(instance, null);\n            injectExtension(instance);\n            instance = postProcessAfterInitialization(instance, null);\n            initExtension(instance);\n            return instance;\n        } catch (Exception e) {\n            throw new IllegalStateException(\n                    \"Can't create adaptive extension \" + type + \", cause: \" + e.getMessage(), e);\n        }\n    }\n\n    private Class<?> getAdaptiveExtensionClass() {\n        getExtensionClasses();\n        if (cachedAdaptiveClass != null) {\n            return cachedAdaptiveClass;\n        }\n        return cachedAdaptiveClass = createAdaptiveExtensionClass();\n    }\n\n    private Class<?> createAdaptiveExtensionClass() {\n        // Adaptive Classes' ClassLoader should be the same with Real SPI interface classes' ClassLoader\n        ClassLoader classLoader = type.getClassLoader();\n        try {\n            if (NativeDetector.inNativeImage()) {\n                return classLoader.loadClass(type.getName() + \"$Adaptive\");","sourceCodeStart":1426,"sourceCodeEnd":1462,"githubUrl":"https://github.com/apache/dubbo/blob/3a3043227f5571d25eb2889de5bca22f2914843b/dubbo-common/src/main/java/org/apache/dubbo/common/extension/ExtensionLoader.java#L1426-L1462","documentation":"Thrown by createAdaptiveExtension() when any Exception escapes the adaptive instance creation pipeline: getAdaptiveExtensionClass().newInstance(), postProcessBeforeInitialization, injectExtension, postProcessAfterInitialization, or initExtension. This is the inner construction error for adaptive extensions and is itself wrapped again by getAdaptiveExtension() into error [140]. The cause is preserved.","triggerScenarios":"First call to getAdaptiveExtension() for an interface with no @Adaptive-annotated implementation, so Dubbo generates and compiles an adaptive class dynamically (createAdaptiveExtensionClass via AdaptiveClassCodeGenerator + Compiler). Failure in javac compilation, instantiation, or SPI setter injection surfaces here. Alternatively an @Adaptive-annotated class whose constructor or setters throw.","commonSituations":"Running on a JRE without a JDK compiler so the generated adaptive source cannot be compiled; the adaptive class's @Adaptive methods reference SPI keys missing from the URL; setter injection of a missing extension dependency; GraalVM native image without the prebuilt $Adaptive class registered for reflection.","solutions":["Inspect getCause() of this exception - it carries the compilation or injection error directly.","Ensure a JDK is on the runtime classpath (javac must be available) or configure an alternative Compiler SPI extension (e.g., JavassistCompiler).","For GraalVM/native-image, ensure type.getName() + '$Adaptive' class is present and registered; NativeDetector.inNativeImage() path loads it directly.","Verify all SPI interfaces referenced by @Adaptive method parameters are themselves resolvable extensions."],"exampleFix":"// before: running on JRE only, javac absent\njava -jre ... app // getAdaptiveExtension() -> [150] cause: compilation failed\n\n// after: run on JDK or add a bytecode compiler dependency\njava -jdk ... app\n// or in pom: add dubbo-compiler/javassist provider as the Compiler SPI impl","handlingStrategy":"try-catch","validationCode":"// Confirm a compiler SPI is available before relying on dynamic adaptive generation\nExtensionLoader<Compiler> cl = extensionDirector.getExtensionLoader(Compiler.class);\ncl.getAdaptiveExtension(); // if this works, the compiler chain is healthy","typeGuard":null,"tryCatchPattern":"try {\n    T adaptive = loader.getAdaptiveExtension();\n} catch (IllegalStateException e) {\n    Throwable root = e.getCause() != null ? e.getCause() : e;\n    if (root.getMessage() != null && root.getMessage().contains(\"compil\")) {\n        log.error(\"Adaptive code generation/compile failed; ensure JDK javac or Javassist is available\", root);\n    }\n    throw e;\n}","preventionTips":["Run on a JDK (not JRE) so javac is available for dynamic adaptive class generation, or bundle a bytecode Compiler extension.","For GraalVM native image, pre-build the $Adaptive class and register it for reflection.","Ensure all SPI interfaces used by @Adaptive method parameters are resolvable."],"tags":["dubbo-spi","adaptive-extension","code-generation","compiler","extension-loader"],"backgroundTag":null,"analyzedSha":"3a3043227f5571d25eb2889de5bca22f2914843b","analyzedAt":"2026-08-14T00:43:19.853Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}