apache/shenyu · error · IllegalArgumentException

Acquire Timeout value must be positive

Error message

Acquire Timeout value must be positive

What it means

For a fixed connection pool, the acquire timeout (milliseconds to wait for a connection from the pool) must be zero or positive; a negative value throws this IllegalArgumentException when building the Reactor Netty ConnectionProvider.

Solutions

1. Set shenyu.httpclient.pool.acquire-timeout to a non-negative millisecond value (e.g. 45000)
2. Remove the key to use the default acquire timeout
3. If 'infinite wait' is desired, use a very large positive value

Example fix

# before
shenyu:
  httpclient:
    pool:
      acquire-timeout: -1
# after
shenyu:
  httpclient:
    pool:
      acquire-timeout: 45000

int acquire = env.getProperty("shenyu.httpclient.pool.acquire-timeout", Integer.class, 45000);
if (acquire < 0) {
    throw new IllegalArgumentException("shenyu.httpclient.pool.acquire-timeout must be >= 0 (ms)");
}

try {
    pool = env.bindProperties(Pool.class);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains("Acquire Timeout")) {
        log.error("acquire-timeout must be a non-negative millisecond value");
    } else throw e;
}

When it happens

Trigger: shenyu.httpclient.pool.type=fixed with pool.acquireTimeout configured as a negative number.

Common situations: Using -1 to mean 'no wait' or 'infinite'; unit mistakes when converting from seconds; stale copied config from another product where -1 means infinite.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

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

Related errors

• Max Connections value must be strictly positive
• client register param must config the appName or contextPath
• The configuration shenyu.discovery.serverList in xml/yml…
• OpenAPI pathKey cannot be null or empty
• OpenAPI methodType cannot be null or empty

AI-assisted analysis of apache/shenyu@567142e072 (2026-09-12). Data as JSON: /api/errors/24dfb4fb86f0323c. Report an issue: GitHub.

Appendix: source

Thrown at shenyu-spring-boot-starter/shenyu-spring-boot-starter-plugin/shenyu-spring-boot-starter-plugin-httpclient/src/main/java/org/apache/shenyu/springboot/starter/plugin/httpclient/HttpClientFactory.java:180

            Optional.ofNullable(pool.getEvictionInterval()).map(Duration::ofMillis).ifPresent(builder::evictInBackground);
            builder.metrics(pool.getMetrics());
            return builder.build();
        }
    }

    /**
     * build fixed connection pool.
     *
     * @param pool    connection pool params
     * @param builder connection provider builder
     */
    public void buildFixedConnectionPool(final Pool pool,
                                         final Builder builder) {
        if (pool.getMaxConnections() <= 0) {
            throw new IllegalArgumentException("Max Connections value must be strictly positive");
        }
        if (pool.getAcquireTimeout() < 0) {
            throw new IllegalArgumentException("Acquire Timeout value must be positive");
        }
        builder.maxConnections(pool.getMaxConnections())
                .pendingAcquireTimeout(Duration.ofMillis(pool.getAcquireTimeout()))
                .pendingAcquireMaxCount(-1);
    }

    /**
     * build elastic connection provider pool.
     *
     * @param builder connection provider builder
     */
    public void buildElasticConnectionPool(final Builder builder) {
        // about the args, please see https://projectreactor.io/docs/netty/release/reference/index.html#_connection_pool_2
        builder.maxConnections(Integer.MAX_VALUE)
                .pendingAcquireTimeout(Duration.ofMillis(0))
                .pendingAcquireMaxCount(-1);
    }

View on GitHub (pinned to 567142e072)