redis/redis-py · critical · InitialHealthCheckFailedError

Initial health check failed. Initial health check policy: {s

Error message

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

What it means

Raised by `MultiDBClient._perform_initial_health_check()` (redis/asyncio/multidb/client.py:411) as InitialHealthCheckFailedError when the initial health-check results do not satisfy the configured `initial_health_check_policy` (`ALL_AVAILABLE`, `MAJORITY_AVAILABLE`, or `ONE_AVAILABLE`). Unlike error 141, this fires earlier — during the initial probe sweep itself — based on the policy predicate rather than the circuit states.

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 da03cdc7e8)

Solutions

Set `initial_health_check_policy=InitialHealthCheck.MAJORITY_AVAILABLE` (or `ONE_AVAILABLE`) in `MultiDbConfig` if not all DBs must be up to start.
Bring every database online (or fix the unreachable/misconfigured ones) before initialize.
Loosen health-check tuning (`health_check_probes`, `health_check_timeout`) if probes are too strict.
Verify the policy name in the error message to know which predicate failed.

Example fix

# before
cfg = MultiDbConfig(
    databases_config=[db_a, db_b, db_c],  # one is down
    # default: initial_health_check_policy=ALL_AVAILABLE
)
await MultiDBClient(cfg).initialize()  # InitialHealthCheckFailedError

# after
from redis.asyncio.multidb.config import InitialHealthCheck
cfg = MultiDbConfig(
    databases_config=[db_a, db_b, db_c],
    initial_health_check_policy=InitialHealthCheck.MAJORITY_AVAILABLE,
)
await MultiDBClient(cfg).initialize()

Defensive patterns

Strategy: validation

Validate before calling

from redis.asyncio.multidb.config import InitialHealthCheck
from redis.multidb.circuit import State as CBState

async def will_pass_initial_policy(client, policy: InitialHealthCheck) -> bool:
    results = await client._check_databases_health()
    healthy = sum(1 for v in results.values() if v)
    total = len(results)
    if policy == InitialHealthCheck.ALL_AVAILABLE:
        return healthy == total
    if policy == InitialHealthCheck.MAJORITY_AVAILABLE:
        return healthy > total / 2
    if policy == InitialHealthCheck.ONE_AVAILABLE:
        return healthy >= 1
    return False

Type guard

from redis.asyncio.multidb.config import InitialHealthCheck

def is_valid_policy(p) -> bool:
    return p in InitialHealthCheck.__members__.values()

Try / catch

from redis.multidb.exception import InitialHealthCheckFailedError

try:
    await client.initialize()
except InitialHealthCheckFailedError as e:
    # inspect e args for the failing policy; lower the bar or bring up DBs
    raise

Prevention

Pick `initial_health_check_policy` to match your availability SLA (MAJORITY_AVAILABLE is usually safer than ALL_AVAILABLE).
Validate every endpoint with a pre-flight PING before starting.
Pre-warm Redis instances before the client initializes.

When it happens

Trigger: Calling `await client.initialize()` (or the first command, which triggers initialize) when too few databases pass their initial health probes for the chosen policy: ALL_AVAILABLE needs every DB healthy, MAJORITY_AVAILABLE needs >half, ONE_AVAILABLE needs at least one. With the default policy ALL_AVAILABLE, a single unhealthy DB fails the check.

Common situations: Default `initial_health_check_policy=ALL_AVAILABLE` failing because one of several databases is down at startup; partial outage in an Active-Active topology; misconfigured health-check probe count/timeout making flaky DBs appear unhealthy.

Related errors

AI-assisted analysis of redis/redis-py@da03cdc7e8 (2026-08-04). Data as JSON: /data/errors/619819434db8a135.json. Report an issue: GitHub.