redis/redis-py · critical · InitialHealthCheckFailedError

Initial health check failed. Initial health check policy

Error message

Initial health check failed. Initial health check policy: {self._config.initial_health_check_policy}

What it means

Raised as InitialHealthCheckFailedError by _perform_initial_health_check() when the aggregate health-check results do not satisfy the configured initial_health_check_policy (ALL_AVAILABLE requires every DB healthy, MAJORITY_AVAILABLE requires >half, ONE_AVAILABLE requires at least one). It stops initialization before recurring health checks and active-database selection run.

Solutions

Lower the bar to InitialHealthCheck.ONE_AVAILABLE or MAJORITY_AVAILABLE if not every region must be up to start.
Fix the failing database(s): check health check logs (the underlying exception is logged in _check_databases_health) and resolve network/TLS/lag issues.
Verify health_check_url is set for LagAwareHealthCheck databases and the REST API (port 9443 by default) is reachable.
Increase health_check_timeout / health_check_probes if probes are flaky on slow links.
Retry initialize() with backoff after fixing endpoints — transient cloud blips often clear within seconds.

Example fix

// before
config = MultiDbConfig(
    databases_config=[db_primary, db_secondary_that_is_down],
    # default initial_health_check_policy = ALL_AVAILABLE -> raises
)

// after
from redis.asyncio.multidb.config import InitialHealthCheck
config = MultiDbConfig(
    databases_config=[db_primary, db_secondary_that_is_down],
    initial_health_check_policy=InitialHealthCheck.ONE_AVAILABLE,
)

Defensive patterns

Strategy: validation

Validate before calling

from redis.asyncio import Redis
from redis.asyncio.multidb.config import InitialHealthCheck

def policy_is_satisfiable(n_total: int, policy: InitialHealthCheck) -> bool:
    if policy == InitialHealthCheck.ALL_AVAILABLE:
        return n_total >= 1  # all must be up; need at least one configured
    if policy == InitialHealthCheck.MAJORITY_AVAILABLE:
        return n_total >= 1
    if policy == InitialHealthCheck.ONE_AVAILABLE:
        return n_total >= 1
    return False

# plus a pre-flight ping sweep against every DatabaseConfig endpoint
async def all_endpoints_ping_ok(config) -> bool:
    for cfg in config.databases_config:
        r = Redis.from_url(cfg.from_url) if cfg.from_url else Redis(**cfg.client_kwargs)
        try:
            if not await r.ping():
                return False
        except Exception:
            return False
        finally:
            await r.aclose()
    return True

Type guard

from redis.asyncio.multidb.config import InitialHealthCheck

def is_valid_initial_policy(p) -> bool:
    return isinstance(p, InitialHealthCheck)

Try / catch

from redis.multidb.exception import InitialHealthCheckFailedError

try:
    await client.initialize()
except InitialHealthCheckFailedError as e:
    logger.error("startup health check failed (policy=%s)", config.initial_health_check_policy)
    # optionally relax policy and retry, or fail the deployment
    raise

Prevention

Pre-flight PING every endpoint before initialize().
Pick the strictest policy your SLO needs; default ALL_AVAILABLE fails if any region is down.
Set health_check_url for LagAwareHealthCheck databases and verify the REST API is reachable.
Tune health_check_timeout/health_check_probes for slow or noisy links.
Retry initialize() with backoff — transient cloud blips often clear quickly.

When it happens

Trigger: Calling initialize() (directly or lazily via the first command) when, for example, policy is ALL_AVAILABLE (the default) and at least one database fails its PingHealthCheck/LagAwareHealthCheck; or MAJORITY_AVAILABLE with too many unhealthy DBs; or ONE_AVAILABLE with every DB unhealthy. The f-string in the message echoes the offending policy.

Common situations: Strict ALL_AVAILABLE policy combined with one misconfigured or temporarily-down region; LagAwareHealthCheck failing because the Redis Enterprise REST API is unreachable or returns high lag; partial network partition at boot; TLS/cert issues on one endpoint.

Related errors

AI-assisted analysis of redis/redis-py@6a6b581b48 (2026-08-10). Data as JSON: /api/errors/619819434db8a135. Report an issue: GitHub.

Appendix: source

Thrown at redis/asyncio/multidb/client.py:411

        Runs initial health check and evaluate healthiness based on initial_health_check_policy.
        """
        results = await self._check_databases_health()
        is_healthy = True

        if self._config.initial_health_check_policy == InitialHealthCheck.ALL_AVAILABLE:
            is_healthy = False not in results.values()
        elif (
            self._config.initial_health_check_policy
            == InitialHealthCheck.MAJORITY_AVAILABLE
        ):
            is_healthy = sum(results.values()) > len(results) / 2
        elif (
            self._config.initial_health_check_policy == InitialHealthCheck.ONE_AVAILABLE
        ):
            is_healthy = True in results.values()

        if not is_healthy:
            raise InitialHealthCheckFailedError(
                f"Initial health check failed. Initial health check policy: {self._config.initial_health_check_policy}"
            )

    async def _check_db_health(self, database: AsyncDatabase) -> bool:
        """
        Runs health checks on the given database until first failure.
        """
        # Health check will setup circuit state
        is_healthy = await self._health_check_policy.execute(
            self._health_checks, database
        )

        if not is_healthy:
            if database.circuit.state != CBState.OPEN:
                database.circuit.state = CBState.OPEN
            return is_healthy
        elif is_healthy and database.circuit.state != CBState.CLOSED:
            database.circuit.state = CBState.CLOSED

View on GitHub (pinned to 6a6b581b48)