eclipse-vertx/vert.x · error · io.vertx.core.VertxException

Cannot read hosts file ${file.getAbsolutePath()}

Error message

Cannot read hosts file ${file.getAbsolutePath()}

What it means

Runtime error while refreshing the hosts file used for local resolution: the configured hosts file path either does not exist, is not a regular file, or could not be parsed by HostsFileParser (IOException). The VertxException aborts the periodic refresh triggered after the refresh period elapsed.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/dns/impl/DnsAddressResolverProvider.java:241

  private void ensureHostsFileFresh(long refreshPeriodNanos) {
    long prev = refreshTimestamp.get();
    long now = System.nanoTime();
    if ((now - prev) >= refreshPeriodNanos && refreshTimestamp.compareAndSet(prev, now)) {
      refreshHostsFile();
    }
  }

  private void refreshHostsFile() {
    HostsFileEntries entries;
    if (hostsPath != null) {
      File file = vertx.fileResolver().resolve(hostsPath).getAbsoluteFile();
      try {
        if (!file.exists() || !file.isFile()) {
          throw new IOException();
        }
        entries = HostsFileParser.parse(file);
      } catch (IOException e) {
        throw new VertxException("Cannot read hosts file " + file.getAbsolutePath());
      }
    } else if (hostsValue != null) {
      try {
        entries = HostsFileParser.parse(new StringReader(hostsValue.toString()));
      } catch (IOException e) {
        throw new VertxException("Cannot read hosts config ", e);
      }
    } else {
      entries = HostsFileParser.parseSilently();
    }
    parsedHostsFile = entries;
  }

  private static class ResolverRegistration {
    private final io.netty.resolver.AddressResolver<InetSocketAddress> resolver;
    private final EventLoop executor;
    ResolverRegistration(io.netty.resolver.AddressResolver<InetSocketAddress> resolver, EventLoop executor) {
      this.resolver = resolver;

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Verify the hosts path configured via AddressResolverOptions.setHostsPath exists and is readable
2. Fix permissions or path typos; the refresh is retried on the next period
3. Use setHostsValue to supply hosts entries inline if no file is available

When it happens

Trigger: Thrown at vertx-core/src/main/java/io/vertx/core/dns/impl/DnsAddressResolverProvider.java:241 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/f6ebb03dffb34cad. Report an issue: GitHub.