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

hostsRefreshPeriod must be >= 0

Error message

hostsRefreshPeriod must be >= 0

What it means

AddressResolverOptions.setHostsRefreshPeriod throws IllegalArgumentException with "hostsRefreshPeriod must be >= 0" for negative values. This setting controls how often (in seconds) the hosts file is re-scanned for changes; 0 disables periodic refresh, but a negative period is an invalid scheduler duration. The check fires at option-construction, typically while building resolver options from JSON.

Source

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

  /**
   * @return the hosts configuration refresh period in time unit specified by {@link #getHostsRefreshPeriodUnit()}.
   */
  public int getHostsRefreshPeriod() {
    return hostsRefreshPeriod;
  }

  /**
   * Set the hosts configuration refresh period in time unit specified by {@link #getHostsRefreshPeriodUnit()}, {@code 0} disables it.
   * <p/>
   * The resolver caches the hosts configuration {@link #hostsPath file} after it has read it. When
   * the content of this file can change, setting a positive refresh period will load the configuration
   * file again when necessary.
   *
   * @param hostsRefreshPeriod the hosts configuration refresh period
   */
  public AddressResolverOptions setHostsRefreshPeriod(int hostsRefreshPeriod) {
    if (hostsRefreshPeriod < 0) {
      throw new IllegalArgumentException("hostsRefreshPeriod must be >= 0");
    }
    this.hostsRefreshPeriod = hostsRefreshPeriod;
    return this;
  }

  /**
   * @return the list of dns server
   */
  public List<String> getServers() {
    return servers;
  }

  /**
   * Set the list of DNS server addresses, an address is the IP  of the dns server, followed by an optional
   * colon and a port, e.g {@code 8.8.8.8} or {code 192.168.0.1:40000}. When the list is empty, the resolver
   * will use the list of the system DNS server addresses from the environment, if that list cannot be retrieved
   * it will use Google's public DNS servers {@code "8.8.8.8"} and {@code "8.8.4.4"}.
   *

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Pass 0 to disable periodic hosts refresh, or a positive number of seconds.
2. Fix the config/JSON source so hostsRefreshPeriod is >= 0 or absent (default 0).
3. Clamp before setting: options.setHostsRefreshPeriod(Math.max(0, configured)).

Example fix

// before
resolverOpts.setHostsRefreshPeriod(-1); // intent: disable
// after
resolverOpts.setHostsRefreshPeriod(0); // 0 disables periodic refresh

int period = configured < 0 ? 0 : configured; // 0 disables refresh
resolverOptions.setHostsRefreshPeriod(period);

try {
  resolverOptions.setHostsRefreshPeriod(v);
} catch (IllegalArgumentException e) {
  throw new IllegalArgumentException("hostsRefreshPeriod must be >= 0 seconds, got " + v, e);
}

When it happens

Trigger: new AddressResolverOptions().setHostsRefreshPeriod(-1); AddressResolverOptions.fromJson with "hostsRefreshPeriod" < 0; config templating that injects -1 as a 'disabled' marker.

Common situations: Using -1 to mean 'never refresh' instead of the documented 0; subtracting values in config math that underflow below 0; copy-pasting an option block where a related TTL field got a negative default.

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

• cacheMinTimeToLive 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/ca25f2d28283148c. Report an issue: GitHub.