{"record":{"id":"3f3451f70b9e2376","repo":"apache/dubbo","slug":"failed-to-create-adaptive-instance","errorCode":null,"errorMessage":"Failed to create adaptive instance: {}","messagePattern":"Failed to create adaptive instance: (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"dubbo-common/src/main/java/org/apache/dubbo/common/extension/ExtensionLoader.java","lineNumber":726,"sourceCode":"            cachedClasses.get().put(name, clazz);\n            cachedInstances.remove(name);\n        } else {\n            if (cachedAdaptiveClass == null) {\n                throw new IllegalStateException(\"Adaptive Extension doesn't exist (Extension \" + type + \")!\");\n            }\n\n            cachedAdaptiveClass = clazz;\n            cachedAdaptiveInstance.set(null);\n        }\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    public T getAdaptiveExtension() {\n        checkDestroyed();\n        Object instance = cachedAdaptiveInstance.get();\n        if (instance == null) {\n            if (createAdaptiveInstanceError != null) {\n                throw new IllegalStateException(\n                        \"Failed to create adaptive instance: \" + createAdaptiveInstanceError.toString(),\n                        createAdaptiveInstanceError);\n            }\n\n            synchronized (cachedAdaptiveInstance) {\n                instance = cachedAdaptiveInstance.get();\n                if (instance == null) {\n                    try {\n                        instance = createAdaptiveExtension();\n                        cachedAdaptiveInstance.set(instance);\n                    } catch (Throwable t) {\n                        createAdaptiveInstanceError = t;\n                        throw new IllegalStateException(\"Failed to create adaptive instance: \" + t.toString(), t);\n                    }\n                }\n            }\n        }\n","sourceCodeStart":708,"sourceCodeEnd":744,"githubUrl":"https://github.com/apache/dubbo/blob/3a3043227f5571d25eb2889de5bca22f2914843b/dubbo-common/src/main/java/org/apache/dubbo/common/extension/ExtensionLoader.java#L708-L744","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the wrapped cause (createAdaptiveInstanceError) in the stack trace to find the real failure — it is the Throwable passed as the second argument.","Ensure at least one method on the SPI interface is annotated @Adaptive(value=\"paramKey\") so Dubbo can generate adaptive routing logic.","Alternatively, provide a hand-written @Adaptive class and register it via addExtension(null, adaptiveClass).","Check for missing dependencies or initialization failures in the adaptive implementation's @Inject setters.","Verify the URL parameter key referenced in @Adaptive(value=...) is consistent with the actual URL parameter types."],"exampleFix":"// before — SPI interface with no @Adaptive method\n@SPI\npublic interface MyRouter {\n    // no @Adaptive method — adaptive generation fails\n    List<Invoker<?>> route(List<Invoker<?>> invokers, URL url, Invocation inv);\n}\n\n// after — add @Adaptive to the method\n@SPI\npublic interface MyRouter {\n    @Adaptive(\"router\")\n    List<Invoker<?>> route(List<Invoker<?>> invokers, URL url, Invocation inv);\n}","handlingStrategy":"try-catch","validationCode":"// Pre-validate: ensure the SPI interface has at least one @Adaptive method\n// or a hand-written @Adaptive class is registered.\nboolean hasAdaptiveMethod = Arrays.stream(type.getMethods())\n    .anyMatch(m -> m.isAnnotationPresent(Adaptive.class));\nif (!hasAdaptiveMethod) {\n    log.warn(\"SPI interface {} has no @Adaptive method — getAdaptiveExtension() may fail\", type);\n}","typeGuard":null,"tryCatchPattern":"try {\n    T adaptive = loader.getAdaptiveExtension();\n} catch (IllegalStateException e) {\n    if (e.getMessage().startsWith(\"Failed to create adaptive instance\")) {\n        Throwable cause = e.getCause();\n        log.error(\"Adaptive extension creation failed for {}\", type, cause);\n        // inspect cause for code-gen errors, missing @Adaptive methods, or injection failures\n    }\n    throw e;\n}","preventionTips":["Ensure at least one method on the SPI interface is annotated @Adaptive(value=\"paramKey\").","Read the wrapped cause exception — it contains the real failure reason (code generation, compilation, injection).","Verify all @Inject dependencies of the adaptive implementation are available on the classpath.","Test getAdaptiveExtension() early in application startup to fail fast on misconfiguration.","Keep @Adaptive value keys consistent with the URL parameters actually used at runtime."],"tags":["dubbo-spi","adaptive","code-generation","initialization","dependency-injection"],"backgroundTag":null,"analyzedSha":"3a3043227f5571d25eb2889de5bca22f2914843b","analyzedAt":"2026-08-14T00:43:19.853Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}