apache/dubbo · error · IllegalStateException

Failed to get extension (%s) name from url (${url}) use keys

Error message

Failed to get extension (%s) name from url (${url}) use keys(%s)

What it means

This is a generated-code template (CODE_EXT_NAME_NULL_CHECK) emitted into the adaptive class. At runtime, the generated $Adaptive class throws IllegalStateException when the extension name cannot be resolved from the URL using the adaptive keys. This means URL.getParameter(key) / getMethodParameter(key) returned null (and no default extension name was configured), so Dubbo cannot determine which concrete extension to load.

Source

Thrown at dubbo-common/src/main/java/org/apache/dubbo/common/extension/AdaptiveClassCodeGenerator.java:66

    private static final String CODE_CLASS_DECLARATION = "public class %s$Adaptive implements %s {\n";

    private static final String CODE_METHOD_DECLARATION = "public %s %s(%s) %s {\n%s}\n";

    private static final String CODE_METHOD_ARGUMENT = "%s arg%d";

    private static final String CODE_METHOD_THROWS = "throws %s";

    private static final String CODE_UNSUPPORTED =
            "throw new UnsupportedOperationException(\"The method %s of interface %s is not adaptive method!\");\n";

    private static final String CODE_URL_NULL_CHECK =
            "if (arg%d == null) throw new IllegalArgumentException(\"url == null\");\n%s url = arg%d;\n";

    private static final String CODE_EXT_NAME_ASSIGNMENT = "String extName = %s;\n";

    private static final String CODE_EXT_NAME_NULL_CHECK = "if(extName == null) "
            + "throw new IllegalStateException(\"Failed to get extension (%s) name from url (\" + url.toString() + \") use keys(%s)\");\n";

    private static final String CODE_INVOCATION_ARGUMENT_NULL_CHECK =
            "if (arg%d == null) throw new IllegalArgumentException(\"invocation == null\"); "
                    + "String methodName = arg%d.getMethodName();\n";

    private static final String CODE_SCOPE_MODEL_ASSIGNMENT =
            "ScopeModel scopeModel = ScopeModelUtil.getOrDefault(url.getScopeModel(), %s.class);\n";
    private static final String CODE_EXTENSION_ASSIGNMENT =
            "%s extension = (%<s)scopeModel.getExtensionLoader(%s.class).getExtension(extName);\n";

    private static final String CODE_EXTENSION_METHOD_INVOKE_ARGUMENT = "arg%d";

    private final Class<?> type;

    private final String defaultExtName;

    public AdaptiveClassCodeGenerator(Class<?> type, String defaultExtName) {
        this.type = type;

View on GitHub (pinned to 3a3043227f)

Solutions

Inspect the exception message for the extension type and the keys tried, then add the missing parameter to the URL.
Set the required parameter on the URL: url = url.addParameter("<key>", "<extension-name>").
If the SPI should have a default extension, configure one in the SPI config file (META-INF/dubbo/...) so defaultExtName is non-null.
Check that the @Adaptive annotation's value() lists the correct parameter keys.

Example fix

// before
URL url = URL.valueOf("dubbo://127.0.0.1:20880/Service");
adaptiveMethod(url); // ext name unresolvable

// after
URL url = URL.valueOf("dubbo://127.0.0.1:20880/Service")
    .addParameter("loadbalance", "random");
adaptiveMethod(url);

Defensive patterns

Strategy: validation

Validate before calling

String[] keys = adaptiveAnnotation.value();
boolean resolvable = false;
for (String k : keys) {
    if (url.getParameter(k) != null) { resolvable = true; break; }
}
if (!resolvable && defaultExtName == null) {
    // extension name cannot be resolved — fix URL or set default
}

Type guard

static boolean canResolveExtensionName(URL url, String[] keys) {
    if (url == null) return false;
    return Arrays.stream(keys).anyMatch(k -> url.getParameter(k) != null);
}

Try / catch

try {
    adaptiveMethod(url);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("Failed to get extension")) {
        url = url.addParameter(keys[0], "default");
        adaptiveMethod(url);
    } else throw e;
}

Prevention

Ensure URLs carry the parameters listed in the @Adaptive annotation.
Configure a default extension name in the SPI config so extName is never null.
Validate URL parameters before calling adaptive methods.

When it happens

Trigger: At runtime, calling a @Adaptive method where the URL lacks all of the parameter keys that the @Adaptive annotation specifies. The code tries url.getParameter("key1"), then "key2", etc., and if all return null and there is no defaultExtName, extName stays null and this fires.

Common situations: A Dubbo URL is missing the protocol/extension-selection parameter. For example calling an adaptive method on a URL that has no "protocol" key and the SPI has no default extension name. Happens when URLs are hand-constructed without the required routing parameters, or when a config-center returns incomplete URL data.

Related errors

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