{"record":{"id":"268680ce6fd8e98d","repo":"apache/dubbo","slug":"adaptive-extension-doesn-t-exist-extension","errorCode":null,"errorMessage":"Adaptive Extension doesn't exist (Extension {})!","messagePattern":"Adaptive Extension doesn't exist \\(Extension (.+?)\\)!","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"dubbo-common/src/main/java/org/apache/dubbo/common/extension/ExtensionLoader.java","lineNumber":712,"sourceCode":"        }\n        if (clazz.isInterface()) {\n            throw new IllegalStateException(\"Input type \" + clazz + \" can't be interface!\");\n        }\n\n        if (!clazz.isAnnotationPresent(Adaptive.class)) {\n            if (StringUtils.isBlank(name)) {\n                throw new IllegalStateException(\"Extension name is blank (Extension \" + type + \")!\");\n            }\n            if (!cachedClasses.get().containsKey(name)) {\n                throw new IllegalStateException(\"Extension name \" + name + \" doesn't exist (Extension \" + type + \")!\");\n            }\n\n            cachedNames.put(clazz, name);\n            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","sourceCodeStart":694,"sourceCodeEnd":730,"githubUrl":"https://github.com/apache/dubbo/blob/3a3043227f5571d25eb2889de5bca22f2914843b/dubbo-common/src/main/java/org/apache/dubbo/common/extension/ExtensionLoader.java#L694-L730","documentation":"Thrown by ExtensionLoader.replaceExtension(String name, Class<?> clazz) when the class is annotated @Adaptive but no adaptive class has been previously registered (cachedAdaptiveClass == null). You cannot replace an adaptive extension that does not exist — use addExtension to register it first.","triggerScenarios":"Calling replaceExtension with an @Adaptive-annotated class when Dubbo has not yet generated or loaded an adaptive class for this SPI type. This can happen if the SPI interface has no @Adaptive methods (so no adaptive class is auto-generated) and no manual adaptive class was previously added.","commonSituations":"Test setup attempts to replace an adaptive class before any adaptive class exists. The SPI interface was modified to remove @Adaptive methods, so no adaptive class is generated. Developer calls replaceExtension instead of addExtension for the first adaptive registration.","solutions":["Use addExtension(null, adaptiveClass) instead of replaceExtension to register the adaptive class for the first time.","Verify whether an adaptive class already exists before trying to replace it.","Check if the SPI interface has @Adaptive methods — if not, Dubbo will not auto-generate an adaptive class."],"exampleFix":"// before — trying to replace non-existent adaptive class\nloader.replaceExtension(null, MyAdaptiveClass.class); // @Adaptive but nothing to replace\n\n// after — add first, then replace if needed later\nloader.addExtension(null, MyAdaptiveClass.class); // registers adaptive class\n// later if updating:\nloader.replaceExtension(null, UpdatedAdaptiveClass.class);","handlingStrategy":"validation","validationCode":"if (clazz.isAnnotationPresent(Adaptive.class)) {\n    boolean adaptiveExists = false;\n    try {\n        loader.getAdaptiveExtension();\n        adaptiveExists = true;\n    } catch (Exception ignored) {}\n    if (adaptiveExists) {\n        loader.replaceExtension(null, clazz);\n    } else {\n        loader.addExtension(null, clazz); // first-time adaptive registration\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use addExtension for first-time adaptive class registration, replaceExtension for updates.","Check whether an adaptive class exists before attempting to replace it.","Understand that SPI interfaces without @Adaptive methods will not have auto-generated adaptive classes."],"tags":["dubbo-spi","adaptive","not-found","registration","deprecated","extension-system"],"backgroundTag":null,"analyzedSha":"3a3043227f5571d25eb2889de5bca22f2914843b","analyzedAt":"2026-08-14T00:43:19.853Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}