apache/druid · warning

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

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.

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)

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 (%ds
• Main Loop: Lost lock ownership check for [%s], stepping down
• Session Keeper: Failed to renew session [%s], it may have ex
• 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.