apache/druid · error · IllegalStateException

Cleaning up idle connections is a bad idea. If your…

Error message

Cleaning up idle connections is a bad idea.  If your services can't handle the max number then lower the max number.

What it means

ResourcePoolConfig's constructor with the cleanIdle flag deliberately refuses to build a connection pool configured to clean up idle connections. The Druid HTTP client authors consider idle-connection eviction harmful (it defeats connection reuse and hides capacity problems), so enabling it is a hard programming error, thrown immediately at config construction time.

Solutions

1. Pass cleanIdle=false, or better, use the 2-arg constructor ResourcePoolConfig(maxPerKey, unusedConnectionTimeoutMillis)
2. If the pool cannot handle the load, lower the configured maxPerKey value or increase service capacity instead of enabling idle cleanup
3. Refactor callers so they no longer construct this deprecated overload

Example fix

// before
new ResourcePoolConfig(10, 60000, true);
// after
new ResourcePoolConfig(10, 60000);

if (useCleanIdleFlagOverload) {
  throw new IllegalArgumentException("cleanIdle is unsupported; use ResourcePoolConfig(maxPerKey, unusedConnectionTimeoutMillis)");
}

try {
  config = new ResourcePoolConfig(maxPerKey, timeout, cleanIdle);
} catch (IllegalStateException e) {
  config = new ResourcePoolConfig(maxPerKey, timeout);
  LOG.warn(e, "cleanIdle unsupported; fell back to 2-arg config");
}

When it happens

Trigger: Calling the deprecated 3-arg ResourcePoolConfig constructor (maxPerKey, unusedConnectionTimeoutMillis, cleanIdle) with cleanIdle=true.

Common situations: Copying old example code that used the third boolean argument; attempting to mitigate pool exhaustion by evicting idle connections; migrating code from an older Druid HTTP client version where the flag existed.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Failed to apply webClientOptions to WebClientOptions. Check…
• No sslContext set, cannot do https
• Ohh no! UnusedConnectionTimeout
• A valid tlsPort needs to specified when druid.enableTlsPort…
• At least one of the druid.enablePlaintextPort or…

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/8fc27b07fe3e4157. Report an issue: GitHub.

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/java/util/http/client/pool/ResourcePoolConfig.java:48

      int maxPerKey,
      long unusedConnectionTimeoutMillis
  )
  {
    this.maxPerKey = maxPerKey;
    this.unusedConnectionTimeoutMillis = unusedConnectionTimeoutMillis;
  }

  @Deprecated
  public ResourcePoolConfig(
      int maxPerKey,
      boolean cleanIdle,
      long unusedConnectionTimeoutMillis
  )
  {
    this(maxPerKey, unusedConnectionTimeoutMillis);

    if (cleanIdle) {
      throw new IllegalStateException(
          "Cleaning up idle connections is a bad idea.  "
          + "If your services can't handle the max number then lower the max number."
      );
    }
  }

  public int getMaxPerKey()
  {
    return maxPerKey;
  }

  public long getUnusedConnectionTimeoutMillis()
  {
    return unusedConnectionTimeoutMillis;
  }
}

View on GitHub (pinned to 9b90983fd2)