apache/dubbo · critical · IllegalStateException

Failed to create adaptive instance: {}

Error message

Failed to create adaptive instance: {}

What it means

Thrown by ExtensionLoader.getAdaptiveExtension() when the adaptive extension instance could not be created. The underlying cause (createAdaptiveInstanceError) is captured and re-thrown as an IllegalStateException wrapping it. The adaptive extension is Dubbo's code-generated or @Adaptive-annotated default implementation used when no specific name is given. Creation can fail due to code generation errors, missing methods with @Adaptive annotation, compilation failures, or dependency injection errors during initialization.

Source

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

            cachedClasses.get().put(name, clazz);
            cachedInstances.remove(name);
        } else {
            if (cachedAdaptiveClass == null) {
                throw new IllegalStateException("Adaptive Extension doesn't exist (Extension " + type + ")!");
            }

            cachedAdaptiveClass = clazz;
            cachedAdaptiveInstance.set(null);
        }
    }

    @SuppressWarnings("unchecked")
    public T getAdaptiveExtension() {
        checkDestroyed();
        Object instance = cachedAdaptiveInstance.get();
        if (instance == null) {
            if (createAdaptiveInstanceError != null) {
                throw new IllegalStateException(
                        "Failed to create adaptive instance: " + createAdaptiveInstanceError.toString(),
                        createAdaptiveInstanceError);
            }

            synchronized (cachedAdaptiveInstance) {
                instance = cachedAdaptiveInstance.get();
                if (instance == null) {
                    try {
                        instance = createAdaptiveExtension();
                        cachedAdaptiveInstance.set(instance);
                    } catch (Throwable t) {
                        createAdaptiveInstanceError = t;
                        throw new IllegalStateException("Failed to create adaptive instance: " + t.toString(), t);
                    }
                }
            }
        }

View on GitHub (pinned to 3a3043227f)

Solutions

1. Read the wrapped cause (createAdaptiveInstanceError) in the stack trace to find the real failure — it is the Throwable passed as the second argument.
2. Ensure at least one method on the SPI interface is annotated @Adaptive(value="paramKey") so Dubbo can generate adaptive routing logic.
3. Alternatively, provide a hand-written @Adaptive class and register it via addExtension(null, adaptiveClass).
4. Check for missing dependencies or initialization failures in the adaptive implementation's @Inject setters.
5. Verify the URL parameter key referenced in @Adaptive(value=...) is consistent with the actual URL parameter types.

Example fix

// before — SPI interface with no @Adaptive method
@SPI
public interface MyRouter {
    // no @Adaptive method — adaptive generation fails
    List<Invoker<?>> route(List<Invoker<?>> invokers, URL url, Invocation inv);
}

// after — add @Adaptive to the method
@SPI
public interface MyRouter {
    @Adaptive("router")
    List<Invoker<?>> route(List<Invoker<?>> invokers, URL url, Invocation inv);
}

// Pre-validate: ensure the SPI interface has at least one @Adaptive method
// or a hand-written @Adaptive class is registered.
boolean hasAdaptiveMethod = Arrays.stream(type.getMethods())
    .anyMatch(m -> m.isAnnotationPresent(Adaptive.class));
if (!hasAdaptiveMethod) {
    log.warn("SPI interface {} has no @Adaptive method — getAdaptiveExtension() may fail", type);
}

try {
    T adaptive = loader.getAdaptiveExtension();
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Failed to create adaptive instance")) {
        Throwable cause = e.getCause();
        log.error("Adaptive extension creation failed for {}", type, cause);
        // inspect cause for code-gen errors, missing @Adaptive methods, or injection failures
    }
    throw e;
}

When it happens

Trigger: Calling getAdaptiveExtension() on an SPI type whose adaptive code generation fails: typically because no method on the interface carries @Adaptive and no hand-written @Adaptive class exists, or because the generated code fails to compile (e.g., an adaptive method's value key references a URL parameter type mismatch). Also fails when injectExtension throws during adaptive instance creation.

Common situations: Custom SPI interface lacks any @Adaptive method, so Dubbo cannot determine which URL parameter to use for adaptive routing. A dependency required by the adaptive implementation's setter injection (@Inject) is missing or fails to initialize. After upgrading Dubbo, the adaptive code generation strategy changed and a previously working interface now fails. Bytecode generation conflict with the JVM version or a restrictive security manager.

Related errors

• Adaptive Extension already exists (Extension ${type})!
• Adaptive Extension doesn't exist (Extension {})!
• Can't create adaptive extension {}, cause: {}
• No such class name in {}
• The java code not endsWith "}", code: {}

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