apache/druid · critical · IllegalStateException

Unable to determine host name

Error message

Unable to determine host name

What it means

DruidNode.getDefaultHost() resolves the machine's canonical hostname via InetAddress.getLocalHost(). If the JVM cannot resolve the local host (misconfigured /etc/hosts, missing hostname entry, DNS issues), it wraps the UnknownHostException in an ISE with this message, aborting node startup.

Solutions

1. Set druid.host explicitly in runtime.properties so getDefaultHost() is never called
2. Add the machine's hostname to /etc/hosts (e.g. 127.0.1.1 myhost) so resolution succeeds
3. Fix DNS/hostname configuration in the container or host image

Example fix

// before
runtime.properties: (no druid.host)
// after
  druid.host=druid-broker-0.druid-broker-headless.default.svc.cluster.local

try {
  String canonical = InetAddress.getLocalHost().getCanonicalHostName();
} catch (UnknownHostException e) {
  throw new IllegalStateException("Fix /etc/hosts or set druid.host explicitly", e);
}

try {
  node = new DruidNode(service, null, true, port, null, false, false);
} catch (ISE e) {
  if (e.getMessage() != null && e.getMessage().contains("Unable to determine host name")) {
    log.fatal("Hostname unresolvable; set druid.host or fix /etc/hosts");
  }
  throw e;
}

When it happens

Trigger: Starting any Druid node on a machine where InetAddress.getLocalHost() throws UnknownHostException — e.g. hostname not in /etc/hosts, container without proper hostname resolution, broken DNS.

Common situations: Kubernetes pods or Docker containers with unresolvable hostnames; /etc/hosts missing the 127.0.0.1 hostname mapping; cloud images without hostname set.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• At least one of the druid.enablePlaintextPort or…
• A valid tlsPort needs to specified when druid.enableTlsPort…
• can't start.
• Cannot start Druid as table
• Config[ ] has been removed. Please use config[ ] instead.

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/37bcbc4eb21e0c71. Report an issue: GitHub.

Appendix: source

Thrown at server/src/main/java/org/apache/druid/server/DruidNode.java:342

  }

  public URI getUriToUse()
  {
    try {
      return new URI(getServiceScheme(), null, host, getPortToUse(), null, null, null);
    }
    catch (URISyntaxException e) {
      throw new RuntimeException(e);
    }
  }

  public static String getDefaultHost()
  {
    try {
      return InetAddress.getLocalHost().getCanonicalHostName();
    }
    catch (UnknownHostException e) {
      throw new ISE(e, "Unable to determine host name");
    }
  }

  @Override
  public boolean equals(Object o)
  {
    if (this == o) {
      return true;
    }
    if (o == null || getClass() != o.getClass()) {
      return false;
    }
    DruidNode druidNode = (DruidNode) o;
    return port == druidNode.port &&
           bindOnHost == druidNode.bindOnHost &&
           plaintextPort == druidNode.plaintextPort &&
           enablePlaintextPort == druidNode.enablePlaintextPort &&
           tlsPort == druidNode.tlsPort &&

View on GitHub (pinned to 9b90983fd2)