{"id":"619819434db8a135","repo":"redis/redis-py","slug":"initial-health-check-failed-initial-health-check","errorCode":null,"errorMessage":"Initial health check failed. Initial health check policy: {self._config.initial_health_check_policy}","messagePattern":"Initial health check failed\\. Initial health check policy: (.+?)","errorType":"exception","errorClass":"InitialHealthCheckFailedError","httpStatus":null,"severity":"critical","filePath":"redis/asyncio/multidb/client.py","lineNumber":411,"sourceCode":"        Runs initial health check and evaluate healthiness based on initial_health_check_policy.\n        \"\"\"\n        results = await self._check_databases_health()\n        is_healthy = True\n\n        if self._config.initial_health_check_policy == InitialHealthCheck.ALL_AVAILABLE:\n            is_healthy = False not in results.values()\n        elif (\n            self._config.initial_health_check_policy\n            == InitialHealthCheck.MAJORITY_AVAILABLE\n        ):\n            is_healthy = sum(results.values()) > len(results) / 2\n        elif (\n            self._config.initial_health_check_policy == InitialHealthCheck.ONE_AVAILABLE\n        ):\n            is_healthy = True in results.values()\n\n        if not is_healthy:\n            raise InitialHealthCheckFailedError(\n                f\"Initial health check failed. Initial health check policy: {self._config.initial_health_check_policy}\"\n            )\n\n    async def _check_db_health(self, database: AsyncDatabase) -> bool:\n        \"\"\"\n        Runs health checks on the given database until first failure.\n        \"\"\"\n        # Health check will setup circuit state\n        is_healthy = await self._health_check_policy.execute(\n            self._health_checks, database\n        )\n\n        if not is_healthy:\n            if database.circuit.state != CBState.OPEN:\n                database.circuit.state = CBState.OPEN\n            return is_healthy\n        elif is_healthy and database.circuit.state != CBState.CLOSED:\n            database.circuit.state = CBState.CLOSED","sourceCodeStart":393,"sourceCodeEnd":429,"githubUrl":"https://github.com/redis/redis-py/blob/da03cdc7e8731092b13e395605c3c1fb2de25de1/redis/asyncio/multidb/client.py#L393-L429","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\ncfg = MultiDbConfig(\n    databases_config=[db_a, db_b, db_c],  # one is down\n    # default: initial_health_check_policy=ALL_AVAILABLE\n)\nawait MultiDBClient(cfg).initialize()  # InitialHealthCheckFailedError\n\n# after\nfrom redis.asyncio.multidb.config import InitialHealthCheck\ncfg = MultiDbConfig(\n    databases_config=[db_a, db_b, db_c],\n    initial_health_check_policy=InitialHealthCheck.MAJORITY_AVAILABLE,\n)\nawait MultiDBClient(cfg).initialize()","handlingStrategy":"validation","validationCode":"from redis.asyncio.multidb.config import InitialHealthCheck\nfrom redis.multidb.circuit import State as CBState\n\nasync def will_pass_initial_policy(client, policy: InitialHealthCheck) -> bool:\n    results = await client._check_databases_health()\n    healthy = sum(1 for v in results.values() if v)\n    total = len(results)\n    if policy == InitialHealthCheck.ALL_AVAILABLE:\n        return healthy == total\n    if policy == InitialHealthCheck.MAJORITY_AVAILABLE:\n        return healthy > total / 2\n    if policy == InitialHealthCheck.ONE_AVAILABLE:\n        return healthy >= 1\n    return False","typeGuard":"from redis.asyncio.multidb.config import InitialHealthCheck\n\ndef is_valid_policy(p) -> bool:\n    return p in InitialHealthCheck.__members__.values()","tryCatchPattern":"from redis.multidb.exception import InitialHealthCheckFailedError\n\ntry:\n    await client.initialize()\nexcept InitialHealthCheckFailedError as e:\n    # inspect e args for the failing policy; lower the bar or bring up DBs\n    raise","preventionTips":["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."],"tags":["multidb","initialization","health","configuration"],"analyzedSha":"da03cdc7e8731092b13e395605c3c1fb2de25de1","analyzedAt":"2026-08-04T20:26:47.563Z","schemaVersion":2}