What causes "[http-client] invalid read timeout:{}" in alibaba/nacos?

Set MAINTAINER_CLIENT_READ_TIMEOUT_KEY to a valid integer in milliseconds (e.g. 30000).

alibaba/nacos · error · IllegalArgumentException

[http-client] invalid read timeout:{}

Error message

[http-client] invalid read timeout:{}

What it means

Thrown by ParamUtil.initReadTimeout as an IllegalArgumentException when the read-timeout configuration value cannot be parsed as an integer. The property key is MAINTAINER_CLIENT_READ_TIMEOUT_KEY with a default of DEFAULT_READ_TIMEOUT. Runs at class-load time in the ParamUtil static initializer.

Source

Thrown at maintainer-client/src/main/java/com/alibaba/nacos/maintainer/client/utils/ParamUtil.java:100

        try {
            return Integer.parseInt(connectTimeoutStr);
        } catch (NumberFormatException e) {
            final String msg = "[http-client] invalid connect timeout:" + connectTimeoutStr;
            LOGGER.error("[settings] {}", msg, e);
            throw new IllegalArgumentException(msg, e);
        }
    }
    
    private static int initReadTimeout() {
        String readTimeoutStr =
            NacosClientProperties.PROTOTYPE.getProperty(MAINTAINER_CLIENT_READ_TIMEOUT_KEY,
                DEFAULT_READ_TIMEOUT);
        try {
            return Integer.parseInt(readTimeoutStr);
        } catch (NumberFormatException e) {
            final String msg = "[http-client] invalid read timeout:" + readTimeoutStr;
            LOGGER.error("[settings] {}", msg, e);
            throw new IllegalArgumentException(msg, e);
        }
    }
    
    private static int initMaxRetryTimes() {
        String maxRetryTimesStr =
            NacosClientProperties.PROTOTYPE.getProperty(MAINTAINER_CLIENT_MAX_RETRY_TIMES_KEY,
                String.valueOf(DEFAULT_MAX_RETRY_TIMES));
        try {
            return Integer.parseInt(maxRetryTimesStr);
        } catch (NumberFormatException e) {
            final String msg = "[http-client] invalid max retry times:" + maxRetryTimesStr;
            LOGGER.error("[settings] {}", msg, e);
            throw new IllegalArgumentException(msg, e);
        }
    }
    
    private static long initRefreshIntervalMills() {
        String refreshIntervalMillsStr = NacosClientProperties.PROTOTYPE.getProperty(

View on GitHub (pinned to 9b989acdf1)

Solutions

Set MAINTAINER_CLIENT_READ_TIMEOUT_KEY to a valid integer in milliseconds (e.g. 30000).
Remove the custom override to use the default value.
Audit all config sources (properties files, -D flags, env vars) for non-numeric read-timeout values.

Example fix

# before
nacos.maintainer.client.read.timeout=30s

# after
nacos.maintainer.client.read.timeout=30000

Defensive patterns

Strategy: validation

Validate before calling

String raw = System.getProperty("nacos.maintainer.client.read.timeout", "");
if (!raw.isEmpty()) {
    try { Integer.parseInt(raw); } catch (NumberFormatException e) {
    throw new IllegalArgumentException("read.timeout must be a numeric millisecond value, got: " + raw);
    }
}

Prevention

Specify read timeout as a raw integer in milliseconds.
Run a config validation pass at startup to catch non-numeric timeout values before ParamUtil loads.
Keep a documented default in config templates so overrides are intentional.

When it happens

Trigger: Setting the system property or environment variable for MAINTAINER_CLIENT_READ_TIMEOUT_KEY to a non-numeric string (e.g. '30s', 'fast'). NumberFormatException is caught, logged, and re-thrown as IllegalArgumentException.

Common situations: Properties file or JVM argument uses a duration suffix ('30s') instead of a raw millisecond integer. Misconfigured environment variable. Config templating bug that injected a non-numeric placeholder.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/827e30a7f6b1bd49. Report an issue: GitHub.