eclipse-vertx/vert.x · error · java.lang.IllegalArgumentException

cacheMinTimeToLive must be >= 0

Error message

cacheMinTimeToLive must be >= 0

What it means

AddressResolverOptions.setCacheMinTimeToLive throws IllegalArgumentException with "cacheMinTimeToLive must be >= 0" when given a negative TTL. This setting (in seconds) clamps cached DNS entries to a minimum lifetime regardless of the record's TTL; negative values are invalid clamp bounds. Validation is eager, most often reached via AddressResolverOptions.fromJson while bootstrapping the resolver.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/dns/AddressResolverOptions.java:331

  }

  /**
   * @return the cache min TTL in seconds
   */
  public int getCacheMinTimeToLive() {
    return cacheMinTimeToLive;
  }

  /**
   * Set the cache minimum TTL value in seconds. After resolution successful IP addresses are cached with their DNS response TTL,
   * use this to set a minimum value to all responses TTL.
   *
   * @param cacheMinTimeToLive the cache min TTL in seconds
   * @return a reference to this, so the API can be used fluently
   */
  public AddressResolverOptions setCacheMinTimeToLive(int cacheMinTimeToLive) {
    if (cacheMinTimeToLive < 0) {
      throw new IllegalArgumentException("cacheMinTimeToLive must be >= 0");
    }
    this.cacheMinTimeToLive = cacheMinTimeToLive;
    return this;
  }

  /**
   * @return the cache max TTL in seconds
   */
  public int getCacheMaxTimeToLive() {
    return cacheMaxTimeToLive;
  }

  /**
   * Set the cache maximum TTL value in seconds. After successful resolution IP addresses are cached with their DNS response TTL,
   * use this to set a maximum value to all responses TTL.
   *
   * @param cacheMaxTimeToLive the cache max TTL in seconds
   * @return a reference to this, so the API can be used fluently

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Pass 0 (no minimum clamp) or a positive number of seconds.
2. Ensure the paired setCacheMaxTimeToLive >= setCacheMinTimeToLive to keep the cache range sensible.
3. Validate/clamp the JSON field before fromJson: use Math.max(0, value) or reject the config.

Example fix

// before
resolverOpts.setCacheMinTimeToLive(-1); // intent: no minimum
// after
resolverOpts.setCacheMinTimeToLive(0); // 0 = no minimum TTL clamp

if (minTtl < 0) throw new IllegalArgumentException("cacheMinTimeToLive must be >= 0");
resolverOptions.setCacheMinTimeToLive(minTtl);

try {
  resolverOptions.setCacheMinTimeToLive(v);
} catch (IllegalArgumentException e) {
  log.warn("Invalid cacheMinTimeToLive {}, defaulting to 0", v);
  resolverOptions.setCacheMinTimeToLive(0);
}

When it happens

Trigger: new AddressResolverOptions().setCacheMinTimeToLive(-1); fromJson with "cacheMinTimeToLive" < 0; tests like testOptions exercising defaults and bounds.

Common situations: Passing -1 to mean 'no minimum' instead of 0; config files where min > max was 'fixed' by negating the min; unit or sign errors when generating options programmatically from user input.

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

• hostsRefreshPeriod must be >= 0
• blockedThreadCheckInterval must be > 0
• maxEventLoopExecuteTime must be > 0
• maxWorkerpExecuteTime must be > 0
• internalBlockingPoolSize must be > 0

AI-assisted analysis of eclipse-vertx/vert.x@fb308bd8c3 (2026-09-06). Data as JSON: /api/errors/9f3d49467e1e903a. Report an issue: GitHub.