apache/shenyu · error · IllegalArgumentException

Max Connections value must be strictly positive

Error message

Max Connections value must be strictly positive

What it means

When the HTTP client connection pool type is fixed, the pool's maxConnections must be a positive integer because Reactor Netty's Builder.maxConnections requires it. A zero or negative configured value throws this IllegalArgumentException at pool build time.

Solutions

1. Set shenyu.httpclient.pool.maxConnections to a positive number (e.g. 20 or higher for heavy load)
2. Remove the maxConnections key to use the default value
3. If you intended unlimited connections, keep a large positive number instead of -1

Example fix

# before
shenyu:
  httpclient:
    pool:
      type: fixed
      max-connections: -1
# after
shenyu:
  httpclient:
    pool:
      type: fixed
      max-connections: 2000

int max = env.getProperty("shenyu.httpclient.pool.max-connections", Integer.class, 20);
if (max <= 0) {
    throw new IllegalArgumentException("shenyu.httpclient.pool.max-connections must be > 0");
}

try {
    pool = env.bindProperties(Pool.class);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains("strictly positive")) {
        log.error("Set a positive max-connections for the fixed pool");
    } else throw e;
}

When it happens

Trigger: shenyu.httpclient.pool.type=fixed with shenyu.httpclient.pool.maxConnections set to 0 or a negative number (typo, unit confusion, or copying a placeholder value).

Common situations: Writing maxConnections: -1 intending 'unlimited'; leaving a 0 default from an edited yml; parsing a string config that defaulted to 0.

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.

Related errors

• Acquire Timeout value must be 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/d0558fc647b2766a. 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:177

            }
            Optional.ofNullable(pool.getMaxIdleTime()).map(Duration::ofMillis).ifPresent(builder::maxIdleTime);
            Optional.ofNullable(pool.getMaxLifeTime()).map(Duration::ofMillis).ifPresent(builder::maxLifeTime);
            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))

View on GitHub (pinned to 567142e072)