apache/dubbo · error · IllegalArgumentException

Not find extension: ${name}

Error message

Not find extension: ${name}

What it means

Thrown by ExtensionLoader.getExtension(String name) when the internal getExtension(name, true) returns null, meaning no extension implementation with that name was found in the SPI configuration. This is the single most common Dubbo SPI error: the requested name is not declared in any META-INF/dubbo/, META-INF/dubbo/internal/, or META-INF/services/ SPI configuration file for the given extension type.

Source

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

    }

    @SuppressWarnings("unchecked")
    public List<T> getLoadedExtensionInstances() {
        checkDestroyed();
        List<T> instances = new ArrayList<>();
        cachedInstances.values().forEach(holder -> instances.add((T) holder.get()));
        return instances;
    }

    /**
     * Find the extension with the given name.
     *
     * @throws IllegalStateException If the specified extension is not found.
     */
    public T getExtension(String name) {
        T extension = getExtension(name, true);
        if (extension == null) {
            throw new IllegalArgumentException("Not find extension: " + name);
        }
        return extension;
    }

    @SuppressWarnings("unchecked")
    public T getExtension(String name, boolean wrap) {
        checkDestroyed();
        if (StringUtils.isEmpty(name)) {
            throw new IllegalArgumentException("Extension name == null");
        }
        if ("true".equals(name)) {
            return getDefaultExtension();
        }
        String cacheKey = name;
        if (!wrap) {
            cacheKey += "_origin";
        }
        final Holder<Object> holder = getOrCreateHolder(cacheKey);

View on GitHub (pinned to 3a3043227f)

Solutions

1. Check the extension name spelling against the SPI config file in META-INF/dubbo/<fully-qualified-interface-name> or META-INF/dubbo/internal/.
2. Verify the Maven/Gradle dependency providing that extension implementation is on the classpath (e.g., dubbo-rpc-dubbo for the 'dubbo' protocol).
3. If it is a custom extension, ensure the SPI config file exists with correct format: 'name=fully.qualified.ClassName' and the class is loadable.
4. Enable DEBUG logging for org.apache.dubbo.common.extension to see which extensions are loaded and which fail.
5. Call loader.getSupportedExtensions() at runtime to list all registered names for the type.

Example fix

// before — typo or missing dep
Protocol protocol = loader.getExtension("dubboo"); // typo

// after — correct name and ensure dependency
Protocol protocol = loader.getExtension("dubbo");
// ensure pom.xml includes:
// <dependency>
//   <groupId>org.apache.dubbo</groupId>
//   <artifactId>dubbo-rpc-dubbo</artifactId>
// </dependency>

Set<String> supported = loader.getSupportedExtensions();
if (!supported.contains(name)) {
    throw new IllegalArgumentException(
        "Extension '" + name + "' not found for type " + type
        + ". Available: " + supported);
}
T ext = loader.getExtension(name);

try {
    T ext = loader.getExtension(name);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Not find extension")) {
        log.error("Extension '{}' not found. Available extensions: {}",
            name, loader.getSupportedExtensions());
    }
    throw e;
}

When it happens

Trigger: Requesting an extension by a name that is misspelled, not registered, or from a missing Dubbo module. For example, getExtension("dubbo") on Protocol when dubbo-rpc-dubbo is not on the classpath, or getExtension("roundrobbin") instead of "roundrobin" on LoadBalance. Also triggered when a custom SPI config file has a syntax error or wrong path.

Common situations: Missing Maven/Gradle dependency for the protocol, serialization, or registry implementation. Typo in the extension name in XML/YAML/annotation configuration. SPI config file placed in the wrong META-INF subdirectory. Custom extension class fails to compile or load (then it's excluded from the name map). After upgrading Dubbo, an extension was renamed or moved to a different artifact.

Related errors

• Extension type == null
• Extension type (${type}) is not an interface!
• Extension type (${type}) is not an extension, because it is
• Extension name {} doesn't exist (Extension {})!
• Adaptive Extension doesn't exist (Extension {})!

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