{"record":{"id":"c27a7b26286d411f","repo":"redis/jedis","slug":"circuitbreaker-getname-failed-to-connect-ple","errorCode":null,"errorMessage":"${circuitBreaker.getName()} failed to connect. Please check configuration and try again.","messagePattern":"(.+?) failed to connect\\. Please check configuration and try again\\.","errorType":"validation","errorClass":"JedisValidationException","httpStatus":null,"severity":"error","filePath":"src/main/java/redis/clients/jedis/mcf/MultiDbConnectionProvider.java","lineNumber":654,"sourceCode":"\n    State originalState = circuitBreaker.getState();\n    try {\n      // Transitions the state machine to a CLOSED state, allowing state transition, metrics and\n      // event publishing. Safe since the activeDatabase has not yet been changed and therefore no\n      // traffic will be routed yet\n      circuitBreaker.transitionToClosedState();\n\n      try (Connection targetConnection = database.getConnection()) {\n        targetConnection.ping();\n      }\n    } catch (Exception e) {\n\n      // If the original state was FORCED_OPEN, then transition it back which stops state\n      // transition, metrics and\n      // event publishing\n      if (State.FORCED_OPEN.equals(originalState)) circuitBreaker.transitionToForcedOpenState();\n\n      throw new JedisValidationException(circuitBreaker.getName()\n          + \" failed to connect. Please check configuration and try again.\", e);\n    }\n  }\n\n  /**\n   * Returns the set of all configured endpoints.\n   * @return the set of all configured endpoints\n   */\n  public Set<Endpoint> getEndpoints() {\n    return new HashSet<>(databaseMap.keySet());\n  }\n\n  public void setActiveDatabase(Endpoint endpoint) {\n    if (endpoint == null) {\n      throw new JedisValidationException(\n          \"Provided endpoint is null. Please use one from the configuration\");\n    }\n    Database database = databaseMap.get(endpoint);","sourceCodeStart":636,"sourceCodeEnd":672,"githubUrl":"https://github.com/redis/jedis/blob/6dac31d4c224fb3257c216f3985340c6f500cdcb/src/main/java/redis/clients/jedis/mcf/MultiDbConnectionProvider.java#L636-L672","documentation":"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.'","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\n.connectionConfig(RedisURI.builder()\n    .host(\"redis-replica.internal\").port(6379).build()) // server actually requires TLS on 6380\n// after\n.connectionConfig(RedisURI.builder()\n    .host(\"redis-replica.internal\").port(6380).ssl(true)\n    .password(\"correctPassword\").build())","handlingStrategy":"try-catch","validationCode":"// Pre-validate target reachability before asking the provider to switch\ntry (Jedis probe = new Jedis(uri.getHost(), uri.getPort())) {\n  if (password != null) probe.auth(user, password);\n  probe.ping();\n}","typeGuard":null,"tryCatchPattern":"try {\n  provider.validateTargetConnection(endpoint);\n} catch (JedisValidationException e) {\n  log.error(\"Target {} failed validation: {}\", endpoint, e.getCause());\n  // keep current active database; fix config or skip this failback target\n}","preventionTips":["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."],"tags":["redis","jedis","connection","multi-db","validation","failover"],"backgroundTag":"connection-refused","analyzedSha":"6dac31d4c224fb3257c216f3985340c6f500cdcb","analyzedAt":"2026-09-08T04:55:01.204Z","contentChangedAt":"2026-09-08T04:55:01.204Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}