apache/dubbo · error · IllegalArgumentException

Illegal affinity rule!

Error message

Illegal affinity rule!

What it means

Thrown by AffinityStateRouter.init() when the affinity rule (affinityKey) is null or blank. The affinity state router routes to providers matching an affinity key; enabling it without supplying an affinity key is a configuration error. Note the constructor also throws IllegalStateException wrapping a ParseException if rule parsing fails.

Source

Thrown at dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/router/affinity/AffinityStateRouter.java:98

        }
    }

    public AffinityStateRouter(URL url, String affinityKey, Double ratio, boolean enabled) {
        super(url);
        this.enabled = enabled;
        this.affinityKey = affinityKey;
        this.ratio = ratio;
        matcherFactories =
                moduleModel.getExtensionLoader(ConditionMatcherFactory.class).getActivateExtensions();
        if (this.enabled) {
            this.init(affinityKey);
        }
    }

    public void init(String rule) {
        try {
            if (rule == null || rule.trim().isEmpty()) {
                throw new IllegalArgumentException("Illegal affinity rule!");
            }
            this.matchMatcher = parseRule(affinityKey);
        } catch (ParseException e) {
            throw new IllegalStateException(e.getMessage(), e);
        }
    }

    private ConditionMatcher parseRule(String rule) throws ParseException {
        ConditionMatcher matcher = getMatcher(rule);
        // Multiple values
        Set<String> values = matcher.getMatches();
        values.add(getUrl().getParameter(rule));
        return matcher;
    }

    @Override
    protected BitList<Invoker<T>> doRoute(
            BitList<Invoker<T>> invokers,

View on GitHub (pinned to 3a3043227f)

Solutions

1. Provide a non-empty affinityKey in the affinity router configuration URL (the parameter name is affinityKey / the AFFINITY_KEY constant).
2. If you do not need affinity routing, disable the router (enabled=false) or remove it from the chain.
3. Double-check the rule string is not trimmed to empty; the check is on rule.trim().isEmpty().

Example fix

# before (broken): affinity enabled with no key
override://0.0.0.0/...?router=affinity&affinity.router.enabled=true

# after
override://0.0.0.0/...?router=affinity&affinity.router.enabled=true&affinityKey=region

// Validate affinity router config before constructing
String key = url.getParameter(AFFINITY_KEY, "");
boolean enabled = url.getParameter(ENABLED_KEY, true);
if (enabled && (key == null || key.trim().isEmpty())) {
    throw new IllegalArgumentException(
        "Affinity router enabled but 'affinityKey' is missing; set it or disable the router.");
}
return new AffinityStateRouter<>(url);

try {
    new AffinityStateRouter<>(url);
} catch (IllegalArgumentException | IllegalStateException e) {
    // router misconfiguration; disable affinity and continue without it, or fail config validation
    log.error("Affinity router disabled due to bad config: " + e.getMessage());
    url = url.addParameter(ENABLED_KEY, false);
}

When it happens

Trigger: Configuring the affinity router (SPI 'affinity') with enabled=true but no 'affinityKey' parameter (it defaults to empty string), or constructing AffinityStateRouter with a null/blank affinityKey while enabled.

Common situations: Enabling the affinity router via URL/registry rule but omitting the affinityKey field; a malformed mesh/affinity rule where the key was not substituted; misconfiguring the SPI extension URL.

Related errors

• Illegal route rule!
• Illegal route rule!
• DubboMethodArg index >= parameters.length
• route rule can not be empty.
• Invalid configurator rule, please specify at least one param

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