apache/dubbo · error · IllegalStateException

System property [%s] does not define in org.apache.dubbo.com

Error message

System property [%s] does not define in org.apache.dubbo.common.constants.CommonConstants

What it means

Thrown by SystemPropertyConfigUtils.getSystemProperty(String key) when key is not in the internal whitelist of known Dubbo system properties. The whitelist is built at class-init from CommonConstants.SystemProperty, ThirdPartyProperty, and DubboProperty inner classes. This is a guardrail that prevents arbitrary System.getProperty lookups through Dubbo's utility, not a missing-property error.

Source

Thrown at dubbo-common/src/main/java/org/apache/dubbo/common/utils/SystemPropertyConfigUtils.java:62

                } catch (IllegalAccessException e) {
                    throw new IllegalStateException(
                            String.format("%s does not have field of %s", clazz.getName(), field.getName()));
                }
            }
        }
    }

    /**
     * Return property of VM.
     *
     * @param key
     * @return
     */
    public static String getSystemProperty(String key) {
        if (containsKey(key)) {
            return System.getProperty(key);
        } else {
            throw new IllegalStateException(String.format(
                    "System property [%s] does not define in org.apache.dubbo.common.constants.CommonConstants", key));
        }
    }

    /**
     * Return property of VM. If not exist, the default value is returned.
     *
     * @param key
     * @param defaultValue
     * @return
     */
    public static String getSystemProperty(String key, String defaultValue) {
        if (containsKey(key)) {
            return System.getProperty(key, defaultValue);
        } else {
            throw new IllegalStateException(String.format(
                    "System property [%s] does not define in org.apache.dubbo.common.constants.CommonConstants", key));
        }

View on GitHub (pinned to 3a3043227f)

Solutions

1. Check CommonConstants.SystemProperty / ThirdPartyProperty / DubboProperty for the exact constant string and use that value.
2. If the property is genuinely custom, use System.getProperty(key) directly instead of this utility.
3. Add the property constant to the appropriate CommonConstants inner class if it should be Dubbo-managed.

Example fix

// before
String v = SystemPropertyConfigUtils.getSystemProperty("dubbo.application.name");
// rejected if the constant is registered under a different string

// after
// use the canonical constant
String v = SystemPropertyConfigUtils.getSystemProperty(
    CommonConstants.DubboProperty.DUBBO_APPLICATION_NAME);

// Check if the key is in the Dubbo whitelist before calling
// Keys are String constants in CommonConstants.SystemProperty, .ThirdPartyProperty, .DubboProperty
// For non-whitelisted keys, use System.getProperty(key) directly

When it happens

Trigger: Calling getSystemProperty("my.custom.key") where the key is not a String constant in any of the three CommonConstants inner classes. Even if the system property exists on the JVM, the method rejects unknown keys.

Common situations: Migrating from System.getProperty to this utility for a property that was never registered in CommonConstants; typo in a known property name; new Dubbo property not yet added to the whitelist constant.

Related errors

• already exists bean with same name and type, name=${name}, t
• expected single matching bean but found ${size} candidates f
• Any annotation of [%s] can't be annotated in the service typ
• Address is not allowed to be empty, please re-enter.
• unterminated escape sequence at index ${i} of: ${str}

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