apache/dubbo · critical · IllegalStateException

Can't create adaptive extension {}, cause: {}

Error message

Can't create adaptive extension {}, cause: {}

What it means

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.

Source

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

        String name = clazz.getSimpleName();
        if (name.endsWith(type.getSimpleName())) {
            name = name.substring(0, name.length() - type.getSimpleName().length());
        }
        return name.toLowerCase();
    }

    @SuppressWarnings("unchecked")
    private T createAdaptiveExtension() {
        try {
            T instance = (T) getAdaptiveExtensionClass().newInstance();
            instance = postProcessBeforeInitialization(instance, null);
            injectExtension(instance);
            instance = postProcessAfterInitialization(instance, null);
            initExtension(instance);
            return instance;
        } catch (Exception e) {
            throw new IllegalStateException(
                    "Can't create adaptive extension " + type + ", cause: " + e.getMessage(), e);
        }
    }

    private Class<?> getAdaptiveExtensionClass() {
        getExtensionClasses();
        if (cachedAdaptiveClass != null) {
            return cachedAdaptiveClass;
        }
        return cachedAdaptiveClass = createAdaptiveExtensionClass();
    }

    private Class<?> createAdaptiveExtensionClass() {
        // Adaptive Classes' ClassLoader should be the same with Real SPI interface classes' ClassLoader
        ClassLoader classLoader = type.getClassLoader();
        try {
            if (NativeDetector.inNativeImage()) {
                return classLoader.loadClass(type.getName() + "$Adaptive");

View on GitHub (pinned to 3a3043227f)

Solutions

1. Inspect getCause() of this exception - it carries the compilation or injection error directly.
2. Ensure a JDK is on the runtime classpath (javac must be available) or configure an alternative Compiler SPI extension (e.g., JavassistCompiler).
3. For GraalVM/native-image, ensure type.getName() + '$Adaptive' class is present and registered; NativeDetector.inNativeImage() path loads it directly.
4. Verify all SPI interfaces referenced by @Adaptive method parameters are themselves resolvable extensions.

Example fix

// before: running on JRE only, javac absent
java -jre ... app // getAdaptiveExtension() -> [150] cause: compilation failed

// after: run on JDK or add a bytecode compiler dependency
java -jdk ... app
// or in pom: add dubbo-compiler/javassist provider as the Compiler SPI impl

// Confirm a compiler SPI is available before relying on dynamic adaptive generation
ExtensionLoader<Compiler> cl = extensionDirector.getExtensionLoader(Compiler.class);
cl.getAdaptiveExtension(); // if this works, the compiler chain is healthy

try {
    T adaptive = loader.getAdaptiveExtension();
} catch (IllegalStateException e) {
    Throwable root = e.getCause() != null ? e.getCause() : e;
    if (root.getMessage() != null && root.getMessage().contains("compil")) {
        log.error("Adaptive code generation/compile failed; ensure JDK javac or Javassist is available", root);
    }
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• More than 1 adaptive class found: {}, {}
• No such class name in {}
• The java code not endsWith "}", code: {}
• Failed to compile class, cause: {}, class: {}, code: {} , s
• Compilation failed. class: {}, diagnostics: {}

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