apache/dubbo · error · IllegalStateException

Input type ${clazz} doesn't implement the Extension ${type}

Error message

Input type ${clazz} doesn't implement the Extension ${type}

What it means

Thrown by ExtensionLoader.addExtension(String name, Class<?> clazz) when the provided class does not implement or extend the SPI interface type (type) that this ExtensionLoader manages. Dubbo requires that programmatically registered extensions are assignable to the extension point interface. The check uses type.isAssignableFrom(clazz).

Source

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

     */
    public String getDefaultExtensionName() {
        getExtensionClasses();
        return cachedDefaultName;
    }

    /**
     * Register new extension via API
     *
     * @param name  extension name
     * @param clazz extension class
     * @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 + ")!");

View on GitHub (pinned to 3a3043227f)

Solutions

1. Verify that clazz implements the interface that the ExtensionLoader was created for (the type field).
2. Ensure you are calling addExtension on the correct ExtensionLoader (for the right SPI type).
3. Make the class implement the SPI interface if it was supposed to.

Example fix

// before — class doesn't implement the SPI interface
loader.addExtension("custom", WrongClass.class);
// WrongClass does not implement Protocol

// after
class CustomProtocol implements Protocol { ... }
loader.addExtension("custom", CustomProtocol.class);

if (!type.isAssignableFrom(clazz)) {
    throw new IllegalStateException(
        clazz + " must implement " + type.getName() + " to be registered as an extension");
}
loader.addExtension(name, clazz);

static boolean implementsSpi(Class<?> implClass, Class<?> spiType) {
    return implClass != null && spiType != null && spiType.isAssignableFrom(implClass);
}

When it happens

Trigger: Calling addExtension with a class that implements a different interface or none at all. For example, registering MySerializer.class on an ExtensionLoader<Protocol> by mistake, or registering a class that was refactored to no longer implement the SPI interface.

Common situations: Developer registers a test stub or mock that forgot to implement the SPI interface. A copy-paste error uses the wrong ExtensionLoader instance. After refactoring, the implementation class was changed to extend a different base class and no longer satisfies the interface.

Related errors

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

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