redis/jedis · error · JedisValidationException

failed to connect. Please check configuration and try again.

Error message

${circuitBreaker.getName()} failed to connect. Please check configuration and try again.

What it means

validateTargetConnection verifies that a target database can actually accept traffic before the failover/failback switches to it: it moves the endpoint's Resilience4j circuit breaker to CLOSED, opens a connection, and PINGs it. If any step throws (connection refused, auth error, timeout), the original FORCED_OPEN state is restored if needed and a JedisValidationException wrapping the cause is thrown with '<circuitBreakerName> failed to connect. Please check configuration and try again.'

Solutions

Inspect the wrapped cause (e.getCause()) of the JedisValidationException — it holds the real connection/auth error.
Confirm the target endpoint is reachable and answers PING (redis-cli -h <host> -p <port> PING) from the application host.
Verify the connection config for that database in MultiDbConfig: host, port, user, password, SSL/TLS settings.
If Redis requires auth, ensure credentials match ACL config; if TLS, match the server's tls-port configuration.

Example fix

// before
.connectionConfig(RedisURI.builder()
    .host("redis-replica.internal").port(6379).build()) // server actually requires TLS on 6380
// after
.connectionConfig(RedisURI.builder()
    .host("redis-replica.internal").port(6380).ssl(true)
    .password("correctPassword").build())

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-validate target reachability before asking the provider to switch
try (Jedis probe = new Jedis(uri.getHost(), uri.getPort())) {
  if (password != null) probe.auth(user, password);
  probe.ping();
}

Try / catch

try {
  provider.validateTargetConnection(endpoint);
} catch (JedisValidationException e) {
  log.error("Target {} failed validation: {}", endpoint, e.getCause());
  // keep current active database; fix config or skip this failback target
}

Prevention

Always inspect e.getCause() — the real connect/auth/timeout error is wrapped.
Match TLS settings (ssl(true) and port) with the server's tls-port configuration.
Test failback targets with redis-cli PING from the app host before enabling failback.
Keep credentials for all databases in sync with server ACL changes.

When it happens

Trigger: Calling MultiDbConnectionProvider.validateTargetConnection(endpoint) (directly, or via MultiDbClient's connection-validation flow e.g. onConnectionValidated/failover validation) where database.getConnection() or targetConnection.ping() throws — target Redis down, wrong credentials, TLS mismatch, or network unreachable.

Common situations: Failback to a replica that has not yet caught up or is stopped; validating a newly added database with mistyped host/port/password; TLS enabled on the client but not the server (or vice versa); firewall blocking the validation connection from the app host.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

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

Appendix: source

Thrown at src/main/java/redis/clients/jedis/mcf/MultiDbConnectionProvider.java:654

    State originalState = circuitBreaker.getState();
    try {
      // Transitions the state machine to a CLOSED state, allowing state transition, metrics and
      // event publishing. Safe since the activeDatabase has not yet been changed and therefore no
      // traffic will be routed yet
      circuitBreaker.transitionToClosedState();

      try (Connection targetConnection = database.getConnection()) {
        targetConnection.ping();
      }
    } catch (Exception e) {

      // If the original state was FORCED_OPEN, then transition it back which stops state
      // transition, metrics and
      // event publishing
      if (State.FORCED_OPEN.equals(originalState)) circuitBreaker.transitionToForcedOpenState();

      throw new JedisValidationException(circuitBreaker.getName()
          + " failed to connect. Please check configuration and try again.", e);
    }
  }

  /**
   * Returns the set of all configured endpoints.
   * @return the set of all configured endpoints
   */
  public Set<Endpoint> getEndpoints() {
    return new HashSet<>(databaseMap.keySet());
  }

  public void setActiveDatabase(Endpoint endpoint) {
    if (endpoint == null) {
      throw new JedisValidationException(
          "Provided endpoint is null. Please use one from the configuration");
    }
    Database database = databaseMap.get(endpoint);

View on GitHub (pinned to 6dac31d4c2)