apache/dubbo · error · IllegalStateException

Invalid configurator rule, please specify at least one param

Error message

Invalid configurator rule, please specify at least one parameter you want to change in the rule.

What it means

Thrown by ConfigParser.toParameterString() when a configurator ConfigItem has an empty or null parameters map. Dubbo dynamic configuration (override rules) must specify at least one parameter to change (e.g. timeout, weight, retries). A configurator rule that carries no override keys is invalid and rejected during parsing of the YAML/JSON override config.

Source

Thrown at dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/configurator/parser/ConfigParser.java:163

                tmpUrlBuilder.append("&configVersion=").append(config.getConfigVersion());

                urls.add(appendMatchCondition(URL.valueOf(tmpUrlBuilder.toString()), item));
            }
        }
        return urls;
    }

    private static String toParameterString(ConfigItem item) {
        StringBuilder sb = new StringBuilder();
        sb.append("category=");
        sb.append(DYNAMIC_CONFIGURATORS_CATEGORY);
        if (item.getSide() != null) {
            sb.append("&side=");
            sb.append(item.getSide());
        }
        Map<String, String> parameters = item.getParameters();
        if (CollectionUtils.isEmptyMap(parameters)) {
            throw new IllegalStateException("Invalid configurator rule, please specify at least one parameter "
                    + "you want to change in the rule.");
        }

        parameters.forEach((k, v) -> {
            sb.append('&');
            sb.append(k);
            sb.append('=');
            sb.append(v);
        });

        if (CollectionUtils.isNotEmpty(item.getProviderAddresses())) {
            sb.append('&');
            sb.append(OVERRIDE_PROVIDERS_KEY);
            sb.append('=');
            sb.append(CollectionUtils.join(item.getProviderAddresses(), ","));
        } else if (PROVIDER.equals(item.getSide())) {
            sb.append('&');
            sb.append(OVERRIDE_PROVIDERS_KEY);

View on GitHub (pinned to 3a3043227f)

Solutions

1. Add at least one parameter to override in the configurator item, e.g. parameters: { timeout: 2000 } or weight: 200.
2. Validate the YAML structure: ensure the 'parameters' map is present and correctly indented under each config item before publishing.
3. If you intend an empty/no-op rule, remove the configurator entry entirely instead of publishing an empty one.

Example fix

# before (broken)
configVersion: v2.7
configs:
  - items:
      - side: provider
        parameters: {}

# after
configVersion: v2.7
configs:
  - items:
      - side: provider
        parameters:
          timeout: 2000
          weight: 200

// Validate a ConfigItem before publishing/parsing a configurator rule
Map<String, String> params = item.getParameters();
if (item.getSide() == null && CollectionUtils.isEmpty(params)
        && CollectionUtils.isEmpty(item.getProviderAddresses())) {
    throw new IllegalArgumentException(
        "Refusing to publish configurator: add at least one parameter to override (e.g. timeout, weight).");
}
List<URL> urls = ConfigParser.parseConfigurators(rawConfig);

try {
    ConfigParser.parseConfigurators(rawConfig);
} catch (IllegalStateException e) {
    // surface a clear governance-config error to the operator
    throw new ConfigValidationException("Configurator rule invalid: " + e.getMessage()
        + " Add parameters: { timeout: 2000 } under the config item.", e);
}

When it happens

Trigger: Pushing a dynamic configurator rule (override:// config) via the registry/config-center whose config item has side/addresses defined but no actual 'parameters' map (or an empty one). Parsed through ConfigParser.parseConfigurators -> serviceItemToUrls/appItemToUrls -> toParameterString.

Common situations: Writing a Dubbo governance rule (dubbo-admin / nacos config) and forgetting the parameters block; providing only 'providerAddresses' or 'side' without specifying what to override; malformed YAML where the parameters map is mis-indented so it parses as null.

Related errors

• service field in configuration is null.
• Illegal affinity rule!
• Illegal route rule!
• Illegal route rule!
• DubboMethodArg index >= parameters.length

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