{"record":{"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/6a6b581b48225afa0b76912d1028c6035baee932/redis/asyncio/multidb/client.py#L393-L429","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nconfig = MultiDbConfig(\n    databases_config=[db_primary, db_secondary_that_is_down],\n    # default initial_health_check_policy = ALL_AVAILABLE -> raises\n)\n\n// after\nfrom redis.asyncio.multidb.config import InitialHealthCheck\nconfig = MultiDbConfig(\n    databases_config=[db_primary, db_secondary_that_is_down],\n    initial_health_check_policy=InitialHealthCheck.ONE_AVAILABLE,\n)","handlingStrategy":"validation","validationCode":"from redis.asyncio import Redis\nfrom redis.asyncio.multidb.config import InitialHealthCheck\n\ndef policy_is_satisfiable(n_total: int, policy: InitialHealthCheck) -> bool:\n    if policy == InitialHealthCheck.ALL_AVAILABLE:\n        return n_total >= 1  # all must be up; need at least one configured\n    if policy == InitialHealthCheck.MAJORITY_AVAILABLE:\n        return n_total >= 1\n    if policy == InitialHealthCheck.ONE_AVAILABLE:\n        return n_total >= 1\n    return False\n\n# plus a pre-flight ping sweep against every DatabaseConfig endpoint\nasync def all_endpoints_ping_ok(config) -> bool:\n    for cfg in config.databases_config:\n        r = Redis.from_url(cfg.from_url) if cfg.from_url else Redis(**cfg.client_kwargs)\n        try:\n            if not await r.ping():\n                return False\n        except Exception:\n            return False\n        finally:\n            await r.aclose()\n    return True","typeGuard":"from redis.asyncio.multidb.config import InitialHealthCheck\n\ndef is_valid_initial_policy(p) -> bool:\n    return isinstance(p, InitialHealthCheck)","tryCatchPattern":"from redis.multidb.exception import InitialHealthCheckFailedError\n\ntry:\n    await client.initialize()\nexcept InitialHealthCheckFailedError as e:\n    logger.error(\"startup health check failed (policy=%s)\", config.initial_health_check_policy)\n    # optionally relax policy and retry, or fail the deployment\n    raise","preventionTips":["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."],"tags":["multidb","health-check","initialization","config","circuit-breaker"],"backgroundTag":null,"analyzedSha":"6a6b581b48225afa0b76912d1028c6035baee932","analyzedAt":"2026-08-10T12:52:44.840Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}