apache/druid · critical · RuntimeException

Failed to initialize

Error message

Failed to initialize 

What it means

BaseBrokerViewOfConfig.start() wraps any exception thrown while fetching the broker's dynamic configuration (e.g. lookup or server-view config) from the coordinator in a RuntimeException. The comment is explicit: if the fetch fails the broker must not serve queries, so the failure is fatal and retried on restart.

Solutions

1. Verify the coordinator is running and reachable from the broker (curl the coordinator config endpoint).
2. Check druid.selectors.coordinator.serviceName and discovery configuration on the broker.
3. Inspect the wrapped cause 'e' in the broker logs for the real network/HTTP error.
4. Fix network/TLS/firewall issues between broker and coordinator, then restart the broker.

// catch RuntimeException at startup and inspect the cause
try {
  view.start();
} catch (RuntimeException e) {
  if (e.getCause() instanceof IOException) {
    // coordinator unreachable: retry with backoff / alert ops
  }
  throw e; // broker must not serve queries without config
}

When it happens

Trigger: HttpPostQuery failing against the coordinator config endpoint: coordinator down, wrong druid.selectors.coordinator.serviceName/host, network partition, TLS errors, or coordinator returning an error/invalid payload during broker startup.

Common situations: Broker started before coordinator is available; DNS or discovery (ZooKeeper/leader election) misconfiguration; coordinator overloaded returning 5xx; firewalls blocking broker->coordinator HTTP traffic.

Related errors

• Query[ ] url[ ] timed out.
• At most one of 'druid.broker.segment.watchedTiers' and…
• 'druid.coordinator.kill.maxSegments
• 'druid.coordinator.kill.period
• 'druid.coordinator.kill.

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

Appendix: source

Thrown at server/src/main/java/org/apache/druid/client/BaseBrokerViewOfConfig.java:95

  /**
   * Fetch the initial configuration from the Coordinator on broker startup.
   * If the fetch fails, the broker startup will fail with a RuntimeException,
   * preventing the broker from serving queries with stale or missing configuration.
   */
  @LifecycleStart
  public void start()
  {
    try {
      log.info("Fetching %s from Coordinator.", getConfigTypeName());

      DynamicConfig fetchedConfig = fetchConfigFromClient();
      setDynamicConfig(fetchedConfig);

      log.info("Successfully fetched %s: [%s]", getConfigTypeName(), fetchedConfig);
    }
    catch (Exception e) {
      // If the fetch fails, the broker should not serve queries. Throw the exception and try again on restart.
      throw new RuntimeException("Failed to initialize " + getConfigTypeName(), e);
    }
  }
}

View on GitHub (pinned to 9b90983fd2)