redis/jedis · error · JedisConnectionException

Database is not healthy

Error message

Database is not healthy

What it means

MultiDbConnectionProvider wraps per-database connection pools and routes commands to the currently active database. Each pooled endpoint exposes a health flag; getConnection() refuses to hand out a connection from a pool whose isHealthy() check fails, throwing JedisConnectionException("Database is not healthy"). This guards callers from issuing commands to a database that the failover/health-tracking logic has marked down.

Solutions

1. Check endpoint health before use (provider isHealthy()/active endpoint) and fail over to another database before issuing commands
2. Retry against the provider after failover completes — the failover executor usually selects a healthy database automatically
3. Verify the target database is actually running and reachable (network, firewall, Redis process)
4. Inspect health/failover configuration (health check intervals, SslVerifyMode, endpoints list) in the MultiDbClient builder

Example fix

// before
Connection conn = provider.getConnection(); // throws if pool unhealthy
// after
if (provider.isHealthy(endpoint)) {
  Connection conn = provider.getConnection();
} else {
  provider.failoverToAnotherDatabase(endpoint, true);
  Connection conn = provider.getConnection();
}

if (!provider.isHealthy(activeEndpoint)) { provider.failoverToAnotherDatabase(activeEndpoint, true); }

boolean usable(ConnectionPooled pool) { return pool != null && pool.isHealthy(); }

try { Connection c = provider.getConnection(); ... } catch (JedisConnectionException e) { provider.failoverToAnotherDatabase(endpoint, true); /* retry */ }

When it happens

Trigger: Calling ConnectionPooled.getConnection() (or any provider path that fetches a connection from this pool) after the endpoint's health status became unhealthy — e.g. health checks failed, the database was marked inactive during failover, or the connection to that endpoint was lost.

Common situations: Redis Enterprise BDB failover in progress; the configured active endpoint was taken down or restarted; network partition causing the health checker to flag the pool; client pointing at a replica/endpoint that is no longer serving.

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

• Error while validating pooled Connection object.
• Error while validating pooled Jedis object.
• Error while checking availability
• Database can not be removed due to no healthy database…
• Initialization failed due to initialization policy

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

Appendix: source

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

    private Database(Endpoint endpoint, TrackingConnectionPool connectionPool, Retry retry,
        HealthCheck hc, CircuitBreaker circuitBreaker, float weight, MultiDbConfig multiDbConfig) {

      this.endpoint = endpoint;
      this.connectionPool = connectionPool;
      this.retry = retry;
      this.circuitBreaker = circuitBreaker;
      this.weight = weight;
      this.multiDbConfig = multiDbConfig;
      this.healthCheck = hc;
    }

    public Endpoint getEndpoint() {
      return endpoint;
    }

    public Connection getConnection() {
      if (!isHealthy()) throw new JedisConnectionException("Database is not healthy");
      if (connectionPool.isClosed()) {
        connectionPool = TrackingConnectionPool.from(connectionPool);
      }
      return connectionPool.getResource();
    }

    @VisibleForTesting
    public ConnectionPool getConnectionPool() {
      return connectionPool;
    }

    public Retry getRetry() {
      return retry;
    }

    public CircuitBreaker getCircuitBreaker() {
      return circuitBreaker;
    }

View on GitHub (pinned to 6dac31d4c2)