apache/dubbo · error · IllegalArgumentException

url == null

Error message

url == null

What it means

This is a generated-code template (CODE_URL_NULL_CHECK) emitted into the adaptive class for @Adaptive methods. At runtime, the generated $Adaptive class throws IllegalArgumentException("url == null") when the URL-typed parameter passed to the method is null. Every adaptive method requires a non-null URL to resolve the extension name from its parameters.

Source

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

    private static final String CLASS_NAME_INVOCATION = "org.apache.dubbo.rpc.Invocation";

    private static final String CODE_PACKAGE = "package %s;\n";

    private static final String CODE_IMPORTS = "import %s;\n";

    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;

View on GitHub (pinned to 3a3043227f)

Solutions

1. Ensure a non-null URL is constructed and passed to the adaptive method.
2. Use URL.valueOf("dubbo://127.0.0.1:20880/...") or a Dubbo URL builder to create the URL before the call.
3. Trace upstream to find why the URL was null — typically a missing or failed URL construction in the caller.

Example fix

// before
adaptiveProtocol.export(null);

// after
URL url = URL.valueOf("dubbo://127.0.0.1:20880/org.example.Service");
adaptiveProtocol.export(url);

if (url == null) {
    throw new IllegalArgumentException("URL must not be null before calling adaptive method");
}

static boolean hasValidUrl(URL url) {
    return url != null;
}

try {
    adaptiveProtocol.export(url);
} catch (IllegalArgumentException e) {
    if ("url == null".equals(e.getMessage())) {
        url = URL.valueOf(defaultUrl);
        adaptiveProtocol.export(url);
    } else throw e;
}

When it happens

Trigger: At runtime, calling a method on an adaptive extension instance and passing null for the URL parameter (the parameter whose type is org.apache.dubbo.common.URL). The generated null-check fires immediately before any extension resolution.

Common situations: User code or framework code calling an adaptive SPI method (e.g. Protocol.export, Invoker related methods) with a null URL because the URL was never constructed or was lost upstream. Happens during testing when mock setups omit URL construction.

Related errors

• %s argument == null
• %s argument %s() == null
• Failed to get extension (%s) name from url (${url}) use keys
• invocation == null
• Failed to create adaptive class for interface ${type.getName

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