What causes "gRPC query server shutdown failed" in apache/druid?

Generally benign during shutdown — no action needed if it appears only at process exit.

gRPC query server shutdown failed

Error message

gRPC query server shutdown failed

What it means

When the gRPC query server extension stops, GrpcEndpointInitializer.stop blocks until the gRPC server terminates. If that wait is interrupted (thread interrupt during Druid shutdown), the InterruptedException is caught and logged as this warning rather than propagated, because the process is shutting down anyway.

Solutions

Generally benign during shutdown — no action needed if it appears only at process exit.
If seen outside shutdown, find what is interrupting the lifecycle thread (thread dumps, interrupt() callers) and fix the premature interrupt.
Ensure server.shutdown() is called before waiting so blockUntilShutdown completes promptly; restore the interrupt status if you change the code (Thread.currentThread().interrupt()).

Example fix

// before
catch (InterruptedException e) {
  log.warn(e, "gRPC query server shutdown failed");
}
// after
catch (InterruptedException e) {
  Thread.currentThread().interrupt();
  log.warn(e, "gRPC query server shutdown interrupted; continuing shutdown");
}

Defensive patterns

Strategy: try-catch

Type guard

if (server != null) { server.shutdown(); } // null-guard before blocking on shutdown

Try / catch

try {
  server.blockUntilShutdown();
} catch (InterruptedException e) {
  Thread.currentThread().interrupt(); // preserve interrupt status
  log.warn(e, "gRPC server shutdown interrupted");
}

Prevention

Call server.shutdown() (graceful) before blockUntilShutdown() so the wait is short.
Treat this as benign during SIGTERM; only investigate if it appears during normal operation.
Preserve interrupt status in any custom lifecycle code to keep Druid shutdown orderly.
Keep lifecycle stop hooks non-blocking where possible.

When it happens

Trigger: Calling stop() while server.blockUntilShutdown() is waiting, and the calling thread is interrupted — e.g., lifecycle stop during process shutdown, Jetty lifecycle shutdown, or a shutdown hook interrupting worker threads.

Common situations: Normal Druid process termination or SIGTERM handling where lifecycle stop order interrupts the gRPC wait; tests that interrupt threads during teardown.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Related errors

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

Appendix: source

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

      // (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();
      }
      catch (InterruptedException e) {
        // Just warn. We're shutting down anyway, so no need to throw an exception.
        log.warn(e, "gRPC query server shutdown failed");
      }
      server = null;
    }
  }
}

View on GitHub (pinned to 9b90983fd2)