apache/druid · error · IllegalStateException

Fatal error: grpc query server startup failed

Error message

Fatal error: grpc query server startup failed

What it means

GrpcEndpointInitializer.start failed to start the embedded gRPC query server, most commonly because the configured port is already in use. The initializer logs the IOException and rethrows an ISE deliberately, since without the gRPC endpoint the Broker cannot serve gRPC queries, so startup is intentionally aborted.

Solutions

1. Check whether the configured gRPC port is already occupied (netstat/lsof) and free it or change the port in the extension config.
2. Look at the wrapped IOException in the log for the precise bind failure.
3. Ensure no duplicate Broker instances are starting on the same host with the same port.
4. Verify firewall/host binding settings allow listening on the configured interface.

When it happens

Trigger: Thrown at extensions-contrib/grpc-query/src/main/java/org/apache/druid/grpc/server/GrpcEndpointInitializer.java:98 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at extensions-contrib/grpc-query/src/main/java/org/apache/druid/grpc/server/GrpcEndpointInitializer.java:98

        queryScheduler
    );
  }

  @LifecycleStart
  public void start()
  {
    server = new QueryServer(config, driver, authMapper);
    try {
      server.start();
    }
    catch (IOException e) {
      // Indicates an error when gRPC tried to start the server
      // (such the port is already in use.)
      log.error(e, "Fatal error: gRPC query server startup failed");

      // This exception will bring down the Broker as there is not much we can
      // do if we can't start the gRPC endpoint.
      throw new ISE(e, "Fatal error: grpc query server startup failed");
    }
    catch (Throwable t) {
      // Catch-all for other errors. The most likely error is that some class was not found
      // (that is, class loader issues in an IDE, or a jar missing in the extension).
      log.error(t, "Fatal error: gRPC query server startup failed");

      // This exception will bring down the Broker as there is not much we can
      // do if we can't start the gRPC endpoint.
      throw t;
    }
  }

  @LifecycleStop
  public void stop()
  {
    if (server != null) {
      try {
        server.blockUntilShutdown();

View on GitHub (pinned to 9b90983fd2)