apache/dubbo · error · IllegalStateException

Extension name ${name} already exists (Extension ${type})!

Error message

Extension name ${name} already exists (Extension ${type})!

What it means

Thrown by ExtensionLoader.addExtension(String name, Class<?> clazz) when the provided name already exists in cachedClasses (the map of already-loaded extension names to classes). Each extension name within a single SPI type must be unique. This prevents accidental double-registration or conflicting implementations under the same name.

Source

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

     * @throws IllegalStateException when extension with the same name has already been registered.
     */
    public void addExtension(String name, Class<?> clazz) {
        checkDestroyed();
        getExtensionClasses(); // load classes

        if (!type.isAssignableFrom(clazz)) {
            throw new IllegalStateException("Input type " + clazz + " doesn't implement the Extension " + type);
        }
        if (clazz.isInterface()) {
            throw new IllegalStateException("Input type " + clazz + " can't be interface!");
        }

        if (!clazz.isAnnotationPresent(Adaptive.class)) {
            if (StringUtils.isBlank(name)) {
                throw new IllegalStateException("Extension name is blank (Extension " + type + ")!");
            }
            if (cachedClasses.get().containsKey(name)) {
                throw new IllegalStateException("Extension name " + name + " already exists (Extension " + type + ")!");
            }

            cachedNames.put(clazz, name);
            cachedClasses.get().put(name, clazz);
        } else {
            if (cachedAdaptiveClass != null) {
                throw new IllegalStateException("Adaptive Extension already exists (Extension " + type + ")!");
            }

            cachedAdaptiveClass = clazz;
        }
    }

    /**
     * Replace the existing extension via API
     *
     * @param name  extension name
     * @param clazz extension class

View on GitHub (pinned to 3a3043227f)

Solutions

1. If you intend to override an existing extension, use replaceExtension(name, clazz) instead of addExtension.
2. Choose a different, unique name for your custom extension.
3. Check loader.getSupportedExtensions() before registering to see existing names.

Example fix

// before — name conflict with built-in extension
loader.addExtension("dubbo", CustomProtocol.class); // 'dubbo' already exists

// after — use replaceExtension to override, or a new name
loader.replaceExtension("dubbo", CustomProtocol.class);
// or
loader.addExtension("customDubbo", CustomProtocol.class);

if (loader.hasExtension(name)) {
    // use replaceExtension to override, or choose a different name
    loader.replaceExtension(name, clazz);
} else {
    loader.addExtension(name, clazz);
}

When it happens

Trigger: Calling addExtension with a name that was already loaded from an SPI config file or previously registered via addExtension. For example, registering name="dubbo" for a custom Protocol implementation when the built-in dubbo protocol already holds that name.

Common situations: Attempt to override a built-in extension using addExtension instead of replaceExtension. A test setup method called addExtension twice with the same name. A module is loaded twice (e.g., duplicate JAR on classpath) causing double registration.

Related errors

• Adaptive Extension already exists (Extension ${type})!
• Input type ${clazz} doesn't implement the Extension ${type}
• Input type ${clazz} can't be interface!
• Extension name is blank (Extension ${type})!
• Input type ${clazz} doesn't implement Extension ${type}

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