apache/druid · error · IllegalStateException

Consul TLS configuration failed; refusing to fall back to…

Error message

Consul TLS configuration failed; refusing to fall back to HTTP

What it means

When connection.sslClientConfig is present, create() builds an HTTPS Consul client; if building the SSLContext or HTTP client fails, it refuses to silently fall back to plain HTTP (which could leak credentials) and aborts client creation with this message.

Solutions

1. Fix the TLS configuration (truststore/keystore paths, passwords, protocol/algorithm); the cause chain names the exact problem.
2. Verify truststore/keystore files exist and are readable by the Druid process.
3. Remove sslClientConfig only if plaintext HTTP to Consul is genuinely intended.

When it happens

Trigger: Thrown at extensions-contrib/consul-extensions/src/main/java/org/apache/druid/consul/discovery/ConsulClients.java:102 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

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

Appendix: source

Thrown at extensions-contrib/consul-extensions/src/main/java/org/apache/druid/consul/discovery/ConsulClients.java:102

          connection.getPort()
      );
    }

    if (tlsConfigured) {
      try {
        SSLContext sslContext = buildSslContext(sslConfig);
        HttpClient httpClient = createHttpClientWithOptionalBasicAuth(sslContext, basicUser, basicPass, connection, sslConfig);

        String httpsHost = "https://" + connection.getHost();

        ConsulRawClient rawClient = new ConsulRawClient(httpsHost, connection.getPort(), httpClient);
        LOGGER.info("Created Consul client with HTTPS to %s:%d", connection.getHost(), connection.getPort());
        return new ConsulClient(rawClient);
      }
      catch (Exception e) {
        // TLS was explicitly configured; fail fast rather than silently downgrade to HTTP
        LOGGER.error(e, "Failed to configure TLS for Consul client (host: %s, port: %d)", connection.getHost(), connection.getPort());
        throw new IllegalStateException("Consul TLS configuration failed; refusing to fall back to HTTP", e);
      }
    }

    // No TLS configured - use plain HTTP
    HttpClient httpClient = createHttpClientWithOptionalBasicAuth(null, basicUser, basicPass, connection, null);
    String httpHost = "http://" + connection.getHost();
    ConsulRawClient rawClient = new ConsulRawClient(httpHost, connection.getPort(), httpClient);
    LOGGER.info("Created Consul client with HTTP to %s:%d", connection.getHost(), connection.getPort());
    return new ConsulClient(rawClient);
  }

  /**
   * Build SSLContext from ConsulSSLConfig using Druid's standard TLS infrastructure.
   */
  private static SSLContext buildSslContext(ConsulSSLConfig config)
  {
    try {
      return new TLSUtils.ClientSSLContextBuilder()

View on GitHub (pinned to 9b90983fd2)