redis/jedis · error · JedisException

Retry deadline exceeded.

Error message

Retry deadline exceeded.

What it means

RetryableCommandExecutor executes a command with configurable retries against pooled connections. When the retry deadline (derived from the configured timeout/maxAttempts) passes after an attempt, it throws JedisException("Retry deadline exceeded."), suppressing the last underlying exception. It means the command failed repeatedly and the retry time budget is exhausted.

Solutions

1. Check the suppressed cause for the real failure (connect refused vs timeout) and verify Redis is reachable at the configured endpoint.
2. Increase the retry timeout/maxAttempts in the client or RetryableCommandExecutor configuration.
3. Fix pool sizing (increase max pool size / set sane maxWait) if pool exhaustion is the underlying failure.
4. Reduce per-attempt socket timeout so attempts fit inside the deadline.

Example fix

// before
RedisClient.create("redis://localhost:6379")
    .build();
// after
RedisClient.create("redis://localhost:6379")
    .socketTimeout(Duration.ofSeconds(2))
    .maxAttempts(15)
    .build();

try (Jedis j = new Jedis(host, port, 2000)) {
  j.ping(); // endpoint reachable before using the retrying executor
}

try {
  return executor.executeCommand(cmd);
} catch (JedisException e) {
  if (e.getMessage().contains("Retry deadline exceeded")) {
    throw new ServiceUnavailableException(e);
  }
  throw e;
}

When it happens

Trigger: Command execution keeps failing (connection refused, socket timeout, broken connection to a standalone/multi-db endpoint) across attempts until Instant.now() exceeds the deadline inside executeCommand.

Common situations: Redis server down or restarted; connection pool exhausted (pool block timeouts counted as failures); network instability to a standalone or MultiDb endpoint; deadlines too short for the configured maxAttempts.

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.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Cluster retry deadline exceeded.
• Attempting to write to a broken connection.
• Attempting to read from a broken connection.
• Failed to create socket.
• The connection to ' ' failed ssl/tls hostname verification.

AI-assisted analysis of redis/jedis@6dac31d4c2 (2026-09-08). Data as JSON: /api/errors/07d46486ce524c6d. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/redis/clients/jedis/executors/RetryableCommandExecutor.java:71

        return execute(connection, commandObject);

      } catch (JedisConnectionException jce) {
        lastException = jce;
        ++consecutiveConnectionFailures;
        log.debug("Failed connecting to Redis: {}", connection, jce);
        // "- 1" because we just did one, but the attemptsLeft counter hasn't been decremented yet
        boolean reset = handleConnectionProblem(attemptsLeft - 1, consecutiveConnectionFailures, deadline);
        if (reset) {
          consecutiveConnectionFailures = 0;
        }
      } finally {
        if (connection != null) {
          connection.close();
        }
      }
      if (Instant.now().isAfter(deadline)) {
        throw new JedisException("Retry deadline exceeded.");
      }
    }

    JedisException maxAttemptsException = new JedisException("No more attempts left.");
    if (lastException != null) {
      maxAttemptsException.addSuppressed(lastException);
    }
    throw maxAttemptsException;
  }

  /**
   * WARNING: This method is accessible for the purpose of testing.
   * This should not be used or overriden.
   */
  @VisibleForTesting
  protected <T> T execute(Connection connection, CommandObject<T> commandObject) {
    return connection.executeCommand(commandObject);
  }

View on GitHub (pinned to 6dac31d4c2)