{"record":{"id":"854f5b748293feb0","repo":"apache/dubbo","slug":"extension-name-doesn-t-exist-extension","errorCode":null,"errorMessage":"Extension name {} doesn't exist (Extension {})!","messagePattern":"Extension name (.+?) 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":704,"sourceCode":"     */\n    @Deprecated\n    public void replaceExtension(String name, Class<?> clazz) {\n        checkDestroyed();\n        getExtensionClasses(); // load classes\n\n        if (!type.isAssignableFrom(clazz)) {\n            throw new IllegalStateException(\"Input type \" + clazz + \" doesn't implement Extension \" + type);\n        }\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();","sourceCodeStart":686,"sourceCodeEnd":722,"githubUrl":"https://github.com/apache/dubbo/blob/3a3043227f5571d25eb2889de5bca22f2914843b/dubbo-common/src/main/java/org/apache/dubbo/common/extension/ExtensionLoader.java#L686-L722","documentation":"Thrown by ExtensionLoader.replaceExtension(String name, Class<?> clazz) when the provided name does not exist in cachedClasses. Unlike addExtension (which rejects existing names), replaceExtension requires the name to ALREADY exist — you can only replace something that is currently registered. This guard uses !cachedClasses.get().containsKey(name).","triggerScenarios":"Calling replaceExtension with a name that was never registered, is misspelled, or belongs to a different SPI type. For example, replaceExtension(\"myProto\", ...) when only 'dubbo', 'rest', etc. exist for Protocol.","commonSituations":"Developer tries to replace a custom extension that was never added (should use addExtension instead). Typo in the extension name. The extension was loaded under a different name than expected. The SPI config file providing that extension was not on the classpath, so it was never loaded.","solutions":["Use addExtension instead of replaceExtension if the extension does not yet exist.","Check loader.getSupportedExtensions() to list valid existing names before calling replaceExtension.","Verify the name spelling against the SPI configuration files."],"exampleFix":"// before — name doesn't exist yet\nloader.replaceExtension(\"customProto\", CustomProtocol.class); // not registered\n\n// after — use addExtension for new, replaceExtension for existing\nif (loader.hasExtension(\"customProto\")) {\n    loader.replaceExtension(\"customProto\", CustomProtocol.class);\n} else {\n    loader.addExtension(\"customProto\", CustomProtocol.class);\n}","handlingStrategy":"validation","validationCode":"if (!loader.hasExtension(name)) {\n    // extension doesn't exist — use addExtension instead\n    loader.addExtension(name, clazz);\n} else {\n    loader.replaceExtension(name, clazz);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Check loader.hasExtension(name) before calling replaceExtension.","Use addExtension for new extensions and replaceExtension for existing ones.","Call loader.getSupportedExtensions() to see valid names before attempting replacement."],"tags":["dubbo-spi","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"}