apache/druid · warning

leaderSessionTtl is ; leader failover may take up to

Error message

leaderSessionTtl is %s; leader failover may take up to %s

What it means

A constructor-time warning logged when the configured Consul leader session TTL exceeds 120 seconds. Consul sessions must be renewed before the TTL lapses; a long TTL means that when a leader dies ungracefully, other nodes may wait up to roughly twice the TTL (lock-delay plus session expiry) before they can acquire the lock. The library logs this so operators know failover will be slow.

Solutions

1. Lower leaderSessionTtl to 120 seconds or less (a value like 30-60s is typical) and rely on the session keeper's renewal at healthCheckInterval/3.
2. If slow failover is unacceptable for your service, keep TTL <= 120s and shorten healthCheckInterval so renewals are frequent.
3. If failover latency is acceptable, set the TTL to <= 120s or consciously accept the documented risk.

Example fix

// before
druid.discovery.consul.leader.sessionTtl=PT10M
// after
druid.discovery.consul.leader.sessionTtl=PT60S

if (config.getLeader().getLeaderSessionTtl().getStandardSeconds() > 120) {
  throw new IllegalArgumentException("leaderSessionTtl must be <= 120s for prompt failover, got: "
      + config.getLeader().getLeaderSessionTtl());
}

When it happens

Trigger: Constructing ConsulLeaderSelector with a ConsulDiscoveryConfig whose leader.leaderSessionTtl duration is set to more than 120 seconds (e.g. druid.discovery.consul.leader.sessionTtl=PT5M in properties).

Common situations: Operators tuning the TTL upward to 'reduce renewal churn' after seeing renewal warnings, copying a config from a deployment that tolerated slow failover, or misconfiguring the duration unit (e.g. hours instead of seconds).

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

• watchSeconds (%ds) is much larger than leaderSessionTtl…
• Main Loop: Lost lock ownership check for
• Session Keeper: Failed to renew session
• can't start
• can't stop

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

Appendix: source

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

  private ScheduledExecutorService sessionKeeperService;
  private volatile String sessionId;
  private volatile boolean stopping = false;
  private long errorRetryCount = 0;

  public ConsulLeaderSelector(
      DruidNode self,
      String lockKey,
      ConsulDiscoveryConfig config,
      ConsulClient consulClient
  )
  {
    this.self = Preconditions.checkNotNull(self, "self");
    this.lockKey = Preconditions.checkNotNull(lockKey, "lockKey");
    this.config = Preconditions.checkNotNull(config, "config");
    this.consulClient = Preconditions.checkNotNull(consulClient, "consulClient");

    if (config.getLeader().getLeaderSessionTtl().getStandardSeconds() > 120) {
      LOGGER.warn("leaderSessionTtl is %s; leader failover may take up to %s",
                  config.getLeader().getLeaderSessionTtl(),
                  Duration.standardSeconds(config.getLeader().getLeaderSessionTtl().getStandardSeconds() * 2));
    }
  }

  @Nullable
  @Override
  public String getCurrentLeader()
  {
    try {
      Response<GetValue> response = consulClient.getKVValue(
          lockKey,
          config.getAuth().getAclToken(),
          buildQueryParams()
      );
      if (response != null && response.getValue() != null && response.getValue().getValue() != null) {
        return new String(Base64.getDecoder().decode(response.getValue().getValue()), StandardCharsets.UTF_8);
      }

View on GitHub (pinned to 9b90983fd2)