redis/jedis · error · JedisConnectionException

Initialization failed due to initialization policy

Error message

Initialization failed due to initialization policy: ${evalCtx}

What it means

While waiting for initialization, MultiDbConnectionProvider iterates the configured databases in descending weight order and, after each endpoint's health status resolves (statusTracker.waitForHealthStatus), re-evaluates the InitializationPolicy. If that re-evaluation returns Decision.FAIL, initialization is aborted with JedisConnectionException. Unlike error 170 (immediate fail), this one fires after waiting for at least one endpoint's health check result, meaning the resolved statuses definitively violate the policy.

Solutions

Check the per-endpoint health statuses in the exception's ConnectionInitializationContext message to identify which database failed.
Restore connectivity/credentials for the unhealthy endpoints; confirm with redis-cli PING from the app host.
Choose a less strict InitializationPolicy (e.g. failover policy that only requires one healthy database) in MultiDbConfig.
Increase health check timeouts/intervals so slow-starting Redis instances are not marked unhealthy during initialization.

Example fix

// before
.initializationPolicy(new AllActiveInitPolicy()) // requires every db healthy
// after
.initializationPolicy(InitializationPolicy.FAILONLY) // init OK once any db is healthy

Defensive patterns

Strategy: validation

Validate before calling

// Ensure at least the highest-weight endpoint is reachable before init
Endpoint primary = config.getDatabases().get(0).getEndpoint();
try (Jedis p = new Jedis(primary.getHost(), primary.getPort())) {
  p.auth(user, password); // throws early on bad credentials
}

Try / catch

try {
  client = MultiDbClient.builder().multiDbConfig(cfg).build();
} catch (JedisConnectionException e) {
  // parse context from message; check which endpoint failed health check
  throw new StartupAbortException("Redis fleet unhealthy at init", e);
}

Prevention

Keep health check timeouts generous enough for slow-starting Redis instances.
Confirm health-check credentials have ACL permissions to run the probe commands.
Monitor Redis availability before deployments so init doesn't race an outage.
Use a policy that needs only one healthy database if partial availability is acceptable.

When it happens

Trigger: Building a MultiDbClient where, after waitForHealthStatus(endpoint) returns for one or more endpoints, ConnectionInitializationContext.conformsTo(policy) returns FAIL — e.g. the first (highest-weight) database's health check resolves as unhealthy and the policy (such as 'all active' or a minimum count) is already violated at that point.

Common situations: Primary Redis is down at application startup and the policy demands all/most databases healthy; health check auth failures (wrong password) marking endpoints unhealthy; health check timeouts due to network partition; too aggressive health check settings causing false unhealthy status.

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/0bffdcc1d28997fd. Report an issue: GitHub.

Appendix: source

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

      // Check if health checks are enabled for this endpoint
      if (healthStatusManager.hasHealthCheck(endpoint)) {
        log.info("Health checks enabled for {}, waiting for result", endpoint);
        // Wait for this database's health status to be determined
        statusTracker.waitForHealthStatus(endpoint);
      } else {
        // No health check configured - assume healthy
        log.debug("No health check configured for database {}, defaulting to HEALTHY", endpoint);
      }

      ConnectionInitializationContext evalCtx = new ConnectionInitializationContext(databaseMap,
          healthStatusManager);
      Decision d = evalCtx.conformsTo(policy);
      log.debug("Policy evaluation after {}: {}", endpoint, d);
      if (d == Decision.SUCCESS) {
        return selectBestAvailableDatabase(sortedDatabases);
      }
      if (d == Decision.FAIL) {
        throw new JedisConnectionException(
            "Initialization failed due to initialization policy: " + evalCtx);
      }
      // else CONTINUE -> move to the next pending endpoint
    }

    // All databases are unhealthy
    throw new JedisConnectionException(
        "All configured databases are unhealthy. Cannot initialize MultiDbConnectionProvider.");
  }

  /**
   * Selects the best available (healthy) database based on weight priority.
   * @param sortedDatabases the list of databases sorted by weight in descending order
   * @return the highest-weighted healthy database
   * @throws JedisConnectionException if no healthy database is available
   */
  private Database selectBestAvailableDatabase(
      List<Map.Entry<Endpoint, Database>> sortedDatabases) {

View on GitHub (pinned to 6dac31d4c2)