What causes "DubboMethodArg index >= parameters.length" in apache/dubbo?

Align the route rule's arg indexes with the actual method signature: each args[].index must be < the method's parameter count.

apache/dubbo · error · IndexOutOfBoundsException

DubboMethodArg index >= parameters.length

Error message

DubboMethodArg index >= parameters.length

What it means

Thrown by DubboMethodMatch.isMatch() (IndexOutOfBoundsException) when a DubboMethodArg in a mesh/virtual-service route match specifies an argument index greater than or equal to the actual number of arguments in the live invocation. The match config references an argument position that the call does not have.

Source

Thrown at dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/router/mesh/rule/virtualservice/match/DubboMethodMatch.java:123

            for (int index = 0; index < argp.size(); index++) {
                boolean match = argp.get(index).isMatch(parameterTypes[index].getName())
                        || argp.get(index).isMatch(parameterTypes[index].getSimpleName());
                if (!match) {
                    return false;
                }
            }
        }

        List<DubboMethodArg> args = getArgs();
        if (args != null && args.size() > 0) {
            if (arguments == null || arguments.length == 0) {
                return false;
            }

            for (DubboMethodArg dubboMethodArg : args) {
                int index = dubboMethodArg.getIndex();
                if (index >= arguments.length) {
                    throw new IndexOutOfBoundsException("DubboMethodArg index >= parameters.length");
                }
                if (!dubboMethodArg.isMatch(arguments[index])) {
                    return false;
                }
            }
        }

        return true;
    }
}

View on GitHub (pinned to 3a3043227f)

Solutions

Align the route rule's arg indexes with the actual method signature: each args[].index must be < the method's parameter count.
After changing a service method signature, update or remove mesh route rules that reference argument indexes.
If the rule should simply not match methods with fewer args, prefer the 'argc' matcher to filter by argument count instead of indexing.

Example fix

# before (broken): rule indexes arg 2 but method has 2 params (index 0,1)
apiType: dubbo
dubbo:
  - services: [{name: FooService}]
    routedBy: [vs1]
  - methods:
      - nameMatch: {mode: exact, value: doStuff}
        args:
          - {index: 2, type: string, strMatch: {mode: exact, value: x}}

# after
        args:
          - {index: 1, type: string, strMatch: {mode: exact, value: x}}

Defensive patterns

Strategy: validation

Validate before calling

// Validate route rule arg indexes against the method signature before registering
for (DubboMethodArg arg : match.getArgs()) {
    if (arg.getIndex() >= method.getParameterCount()) {
        throw new IllegalArgumentException(
            "Route rule arg index " + arg.getIndex() + " out of range for "
                + method.getName() + " (" + method.getParameterCount() + " params)");
    }
}

Try / catch

// The throw happens during routing; catch at the invocation boundary
try {
    return invoker.invoke(inv);
} catch (IndexOutOfBoundsException e) {
    if (e.getMessage().contains("DubboMethodArg index")) {
        log.error("Stale mesh route rule references out-of-range arg; routing degraded", e);
        // fall back: retry without the offending route or alert ops
    }
    throw e;
}

Prevention

Keep mesh route arg indexes in sync with the service method signature.
When a method's parameters change, review and update route rules that index args.
Prefer the argc matcher over arg indexing when the rule only needs argument-count filtering.

When it happens

Trigger: A Dubbo virtual-service (mesh) route rule defines method arg matching with args[].index >= the runtime argument count of the invoked method. isMatch loops the configured args and checks each index against arguments.length; an out-of-range index aborts with this message.

Common situations: Method overloading where the rule was written for a method with more parameters; a stale route rule after a method signature changed (params removed); a rule that assumes 0-based indexing differently than the actual call.

Related errors

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