apache/dubbo · error · IllegalArgumentException

Illegal 'dubbo.config.mode' config value [<configModeStr>],

Error message

Illegal 'dubbo.config.mode' config value [<configModeStr>], available values <Arrays.toString(ConfigMode.values())>

What it means

Thrown by AbstractConfigManager constructor when the 'dubbo.config.mode' property cannot be parsed into a ConfigMode enum value. ConfigMode controls how duplicate unique configs are handled and accepts: STRICT, OVERRIDE, OVERRIDE_ALL, OVERRIDE_IF_ABSENT, IGNORE. The value is uppercased before parsing, so a totally unrecognized token causes IllegalArgumentException wrapping the original EnumParseException.

Source

Thrown at dubbo-common/src/main/java/org/apache/dubbo/config/context/AbstractConfigManager.java:130

    @Override
    public void initialize() throws IllegalStateException {
        if (!initialized.compareAndSet(false, true)) {
            return;
        }
        CompositeConfiguration configuration = scopeModel.modelEnvironment().getConfiguration();

        // dubbo.config.mode
        String configModeStr = (String) configuration.getProperty(ConfigKeys.DUBBO_CONFIG_MODE);
        try {
            if (StringUtils.hasText(configModeStr)) {
                this.configMode = ConfigMode.valueOf(configModeStr.toUpperCase());
            }
        } catch (Exception e) {
            String msg = "Illegal '" + ConfigKeys.DUBBO_CONFIG_MODE + "' config value [" + configModeStr
                    + "], available values " + Arrays.toString(ConfigMode.values());
            logger.error(COMMON_PROPERTY_TYPE_MISMATCH, "", "", msg, e);
            throw new IllegalArgumentException(msg, e);
        }

        // dubbo.config.ignore-duplicated-interface
        String ignoreDuplicatedInterfaceStr =
                (String) configuration.getProperty(ConfigKeys.DUBBO_CONFIG_IGNORE_DUPLICATED_INTERFACE);
        if (ignoreDuplicatedInterfaceStr != null) {
            this.ignoreDuplicatedInterface = Boolean.parseBoolean(ignoreDuplicatedInterfaceStr);
        }

        // print
        Map<String, Object> map = new LinkedHashMap<>();
        map.put(ConfigKeys.DUBBO_CONFIG_MODE, configMode);
        map.put(ConfigKeys.DUBBO_CONFIG_IGNORE_DUPLICATED_INTERFACE, this.ignoreDuplicatedInterface);
        logger.info("Config settings: " + map);
    }

    /**
     * Add the dubbo {@link AbstractConfig config}

View on GitHub (pinned to 3a3043227f)

Solutions

1. Use one of: STRICT, OVERRIDE, OVERRIDE_ALL, OVERRIDE_IF_ABSENT, IGNORE (case-insensitive).
2. Remove the property to accept the default mode if unsure.
3. Check for trailing whitespace or quotes in the property source.

Example fix

# before
dubbo.config.mode=strict_mode
# after
dubbo.config.mode=STRICT

import org.apache.dubbo.config.context.ConfigMode;
import java.util.Arrays;

String raw = System.getProperty("dubbo.config.mode");
if (raw != null && !raw.isBlank()) {
    try {
        ConfigMode.valueOf(raw.toUpperCase());
    } catch (IllegalArgumentException e) {
        throw new IllegalArgumentException("Invalid dubbo.config.mode: " + raw
            + ". Allowed: " + Arrays.toString(ConfigMode.values()));
    }
}

static boolean isValidConfigMode(String s) {
    if (s == null || s.isBlank()) return true;
    try { ConfigMode.valueOf(s.toUpperCase()); return true; } catch (Exception e) { return false; }
}

try {
    // trigger config manager init
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("dubbo.config.mode")) {
        System.clearProperty("dubbo.config.mode"); // fall back to default
    } else throw e;
}

When it happens

Trigger: Setting -Ddubbo.config.mode=strict_mode, dubbo.properties dubbo.config.mode=relaxed, or any string that is not (case-insensitively) one of the five enum constants. Whitespace-embedded values also fail.

Common situations: Using a value from documentation for a different version. Typos like 'overide'. Setting it to a custom mode name assuming extensibility.

Related errors

• Invalid configurator rule, please specify at least one param
• service field in configuration is null.
• Illegal affinity rule!
• Illegal route rule!
• Illegal route rule!

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