apache/druid · error · IllegalArgumentException

A valid tlsPort needs to specified when druid.enableTlsPort

Error message

A valid tlsPort needs to specified when druid.enableTlsPort is set

What it means

Configuration validation in the DruidNode initializer: when both enablePlaintextPort and enableTlsPort are true (druid.enableTlsPort set), the node must know both a plaintext and a TLS port to advertise its services, and this fires when either is null. It runs during node construction (init called from the DruidNode constructor), so a misconfigured runtime.properties (e.g. druid.port/druid.tlsPort absent while TLS is enabled) fails fast at startup; specify both ports when enabling TLS.

Source

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

      host = hostAndPort.getHost();
      portFromHostConfig = hostAndPort.hasPort() ? hostAndPort.getPort() : null;
      if (plainTextPort != null && portFromHostConfig != null && !plainTextPort.equals(portFromHostConfig)) {
        throw new IAE("Conflicting host:port [%s] and port [%d] settings", host, plainTextPort);
      }
      if (portFromHostConfig != null) {
        plainTextPort = portFromHostConfig;
      }
    } else {
      host = getDefaultHost();
    }

    if (enablePlaintextPort && enableTlsPort && ((plainTextPort == null || tlsPort == null)
                                                 || plainTextPort.equals(tlsPort))) {
      // If both plainTExt and tls are enabled then do not allow plaintextPort to be null or
      throw new IAE("plaintextPort and tlsPort cannot be null or same if both http and https connectors are enabled");
    }
    if (enableTlsPort && (tlsPort == null || tlsPort < 0)) {
      throw new IAE("A valid tlsPort needs to specified when druid.enableTlsPort is set");
    }

    if (enablePlaintextPort) {
      // to preserve backwards compatible behaviour
      if (nullHost && plainTextPort == null) {
        plainTextPort = -1;
      } else {
        if (plainTextPort == null) {
          plainTextPort = SocketUtil.findOpenPort(8080);
        }
      }
      this.plaintextPort = plainTextPort;
    } else {
      this.plaintextPort = -1;
    }
    if (enableTlsPort) {
      this.tlsPort = tlsPort;
    } else {

View on GitHub (pinned to 9b90983fd2)

Solutions

Set druid.tlsPort to a valid positive port (e.g. 8281)
If TLS is not intended, set druid.enableTlsPort=false
Audit all runtime.properties for enableTlsPort=true without a matching tlsPort

Example fix

// before
  druid.enableTlsPort=true
  druid.tlsPort=-1
// after
  druid.enableTlsPort=true
  druid.tlsPort=8281

Defensive patterns

Strategy: validation

Validate before calling

if (enableTlsPort && (tlsPort == null || tlsPort < 0)) {
  throw new IllegalArgumentException("Set druid.tlsPort to a positive port when druid.enableTlsPort=true");
}

Try / catch

try {
  node = new DruidNode(service, host, true, plainPort, tlsPort, false, false);
} catch (IllegalArgumentException e) {
  log.fatal("Missing/invalid druid.tlsPort: %s", e.getMessage());
  throw e;
}

Prevention

Never use -1 as tlsPort; -1 only disables the plaintext port
Pair every enableTlsPort=true with an explicit positive druid.tlsPort
Config-lint TLS settings per node role
Document port conventions (e.g. plaintext 8081, TLS 8281) for operators

When it happens

Trigger: druid.enableTlsPort=true with druid.tlsPort missing, or set to a negative number like -1 (which is only legal to disable the plaintext port).

Common situations: Enabling TLS via a global config file while per-node tlsPort keys were never added; using -1 copied from the plaintext-port disable idiom.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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