{"record":{"id":"ca25f2d28283148c","repo":"eclipse-vertx/vert.x","slug":"hostsrefreshperiod-must-be-0","errorCode":null,"errorMessage":"hostsRefreshPeriod must be >= 0","messagePattern":"hostsRefreshPeriod must be >= 0","errorType":"exception","errorClass":"java.lang.IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/dns/AddressResolverOptions.java","lineNumber":255,"sourceCode":"  /**\n   * @return the hosts configuration refresh period in time unit specified by {@link #getHostsRefreshPeriodUnit()}.\n   */\n  public int getHostsRefreshPeriod() {\n    return hostsRefreshPeriod;\n  }\n\n  /**\n   * Set the hosts configuration refresh period in time unit specified by {@link #getHostsRefreshPeriodUnit()}, {@code 0} disables it.\n   * <p/>\n   * The resolver caches the hosts configuration {@link #hostsPath file} after it has read it. When\n   * the content of this file can change, setting a positive refresh period will load the configuration\n   * file again when necessary.\n   *\n   * @param hostsRefreshPeriod the hosts configuration refresh period\n   */\n  public AddressResolverOptions setHostsRefreshPeriod(int hostsRefreshPeriod) {\n    if (hostsRefreshPeriod < 0) {\n      throw new IllegalArgumentException(\"hostsRefreshPeriod must be >= 0\");\n    }\n    this.hostsRefreshPeriod = hostsRefreshPeriod;\n    return this;\n  }\n\n  /**\n   * @return the list of dns server\n   */\n  public List<String> getServers() {\n    return servers;\n  }\n\n  /**\n   * Set the list of DNS server addresses, an address is the IP  of the dns server, followed by an optional\n   * 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\n   * will use the list of the system DNS server addresses from the environment, if that list cannot be retrieved\n   * it will use Google's public DNS servers {@code \"8.8.8.8\"} and {@code \"8.8.4.4\"}.\n   *","sourceCodeStart":237,"sourceCodeEnd":273,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/dns/AddressResolverOptions.java#L237-L273","documentation":"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.","triggerScenarios":"new AddressResolverOptions().setHostsRefreshPeriod(-1); AddressResolverOptions.fromJson with \"hostsRefreshPeriod\" < 0; config templating that injects -1 as a 'disabled' marker.","commonSituations":"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.","solutions":["Pass 0 to disable periodic hosts refresh, or a positive number of seconds.","Fix the config/JSON source so hostsRefreshPeriod is >= 0 or absent (default 0).","Clamp before setting: options.setHostsRefreshPeriod(Math.max(0, configured))."],"exampleFix":"// before\nresolverOpts.setHostsRefreshPeriod(-1); // intent: disable\n// after\nresolverOpts.setHostsRefreshPeriod(0); // 0 disables periodic refresh","handlingStrategy":"validation","validationCode":"int period = configured < 0 ? 0 : configured; // 0 disables refresh\nresolverOptions.setHostsRefreshPeriod(period);","typeGuard":null,"tryCatchPattern":"try {\n  resolverOptions.setHostsRefreshPeriod(v);\n} catch (IllegalArgumentException e) {\n  throw new IllegalArgumentException(\"hostsRefreshPeriod must be >= 0 seconds, got \" + v, e);\n}","preventionTips":["Remember 0 (not -1) is the 'disabled' value for this option","Clamp negative config values to 0 with a logged warning","Cover AddressResolverOptions fromJson in config tests with negative inputs"],"tags":["vertx","dns","configuration","address-resolver"],"backgroundTag":"invalid-config-value","analyzedSha":"fb308bd8c3f12c79f4ae89bef67fadf6c80d036e","analyzedAt":"2026-09-06T11:37:12.241Z","contentChangedAt":"2026-09-06T11:37:12.241Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}