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

cacheMaxTimeToLive must be >= 0

Error message

cacheMaxTimeToLive must be >= 0

What it means

Configuration validation in the fluent setter: setCacheMaxTimeToLive rejects a negative cacheMaxTimeToLive argument. The DNS resolver caches resolved addresses with the DNS response TTL capped at this value, and a negative cap is meaningless, so the setter throws immediately before the options object is mutated.

Source

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

  }

  /**
   * @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
   */
  public AddressResolverOptions setCacheMaxTimeToLive(int cacheMaxTimeToLive) {
    if (cacheMaxTimeToLive < 0) {
      throw new IllegalArgumentException("cacheMaxTimeToLive must be >= 0");
    }
    this.cacheMaxTimeToLive = cacheMaxTimeToLive;
    return this;
  }

  /**
   * @return the cache negative TTL in seconds
   */
  public int getCacheNegativeTimeToLive() {
    return cacheNegativeTimeToLive;
  }

  /**
   * Set the negative cache TTL value in seconds. After a failed hostname resolution, DNS queries won't be retried
   * for a period of time equals to the negative TTL. This allows to reduce the response time of negative replies
   * and reduce the amount of messages to DNS servers.
   *
   * @param cacheNegativeTimeToLive the cache negative TTL in seconds

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Pass a value >= 0 (0 disables the max TTL cap and uses the DNS response TTL as-is)
2. When loading options from JSON via fromJson, sanitize or remove negative cacheMaxTimeToLive entries before constructing AddressResolverOptions

When it happens

Trigger: Thrown at vertx-core/src/main/java/io/vertx/core/dns/AddressResolverOptions.java:353 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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