apache/dubbo · error · IllegalStateException

'${key}' doesn't map to a Integer object

Error message

'${key}' doesn't map to a Integer object

What it means

Thrown by Configuration.getInteger(key, defaultValue) when the configured value for key is present but cannot be parsed as an Integer. Internally, convert(Integer.class, key, defaultValue) throws NumberFormatException, which is caught, logged as COMMON_PROPERTY_TYPE_MISMATCH, and re-thrown wrapped in an IllegalStateException. The error indicates a typo or format error in a Dubbo property that is expected to be numeric.

Source

Thrown at dubbo-common/src/main/java/org/apache/dubbo/common/config/Configuration.java:84

    default int getInt(String key, int defaultValue) {
        Integer i = this.getInteger(key, null);
        return i == null ? defaultValue : i;
    }

    default Integer getInteger(String key, Integer defaultValue) {
        try {
            return convert(Integer.class, key, defaultValue);
        } catch (NumberFormatException e) {
            // 0-2 Property type mismatch.
            interfaceLevelLogger.error(
                    COMMON_PROPERTY_TYPE_MISMATCH,
                    "typo in property value",
                    "This property requires an integer value.",
                    "Actual Class: " + getClass().getName(),
                    e);

            throw new IllegalStateException('\'' + key + "' doesn't map to a Integer object", e);
        }
    }

    default boolean getBoolean(String key) {
        Boolean b = this.getBoolean(key, null);
        if (b != null) {
            return b;
        } else {
            throw new NoSuchElementException('\'' + key + "' doesn't map to an existing object");
        }
    }

    default boolean getBoolean(String key, boolean defaultValue) {
        return this.getBoolean(key, toBooleanObject(defaultValue));
    }

    default Boolean getBoolean(String key, Boolean defaultValue) {
        try {

View on GitHub (pinned to 3a3043227f)

Solutions

1. Inspect the full property key from the exception message and check its configured value in dubbo.properties / application.yml / -D system property / config-center.
2. Correct the value to a valid integer literal (e.g. dubbo.consumer.retries=3 instead of dubbo.consumer.retries=three).
3. If the value is intentionally dynamic, read it as a String via configuration.getString(key) and parse it yourself with Integer.parseInt after validation.
4. Check the COMMON_PROPERTY_TYPE_MISMATCH log entry which prints the actual class and the original NumberFormatException for the exact value.

Example fix

// before (in dubbo.properties)
dubbo.protocol.threads=unlimited

// after
dubbo.protocol.threads=200

String raw = configuration.getString(key);
if (raw == null) return defaultValue;
if (!raw.matches("-?\\d+")) {
    // log and handle non-integer value before calling getInteger
    return defaultValue;
}

try {
    return configuration.getInteger(key, defaultValue);
} catch (IllegalStateException e) {
    if (e.getCause() instanceof NumberFormatException) {
        logger.warn("Non-integer value for key {}, using default", key);
        return defaultValue;
    }
    throw e;
}

When it happens

Trigger: Calling configuration.getInteger("some.key", defaultValue) where the resolved property value is non-numeric (e.g. "abc", "12.5", "true"). Also triggered indirectly by getInt(key) and getInt(key, defaultValue) which delegate to getInteger.

Common situations: Misspelled or mis-typed timeout, port, thread-count, or retry properties in dubbo.properties, application.yml, system properties (-D), or config-center. For example setting dubbo.protocol.port=auto or dubbo.consumer.retries=always. Environment variable overrides from CI/CD pipelines injecting wrong value types.

Related errors

• Try to get '${key}' failed, maybe because this key doesn't m
• '${key}' doesn't map to an existing object
• load config failed, id: <id>, type:<cls.getSimpleName()>
• already exists bean with same name and type, name=${name}, t
• expected single matching bean but found ${size} candidates f

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