{"record":{"id":"071e730713031ded","repo":"redis/redis-py","slug":"initial-health-check-failed-initial-health-check-071e73","errorCode":null,"errorMessage":"Initial health check failed. Initial health check policy: {initial_health_check_policy}","messagePattern":"Initial health check failed\\. Initial health check policy: (.+?)","errorType":"exception","errorClass":"InitialHealthCheckFailedError","httpStatus":null,"severity":"critical","filePath":"redis/multidb/client.py","lineNumber":414,"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    def _on_circuit_state_change_callback(\n        self, circuit: CircuitBreaker, old_state: CBState, new_state: CBState\n    ):\n        if new_state == CBState.HALF_OPEN:\n            self._bg_scheduler.run_coro_fire_and_forget(\n                self._check_db_health, circuit.database\n            )\n            return\n\n        if old_state == CBState.CLOSED and new_state == CBState.OPEN:\n            logger.warning(\n                f\"Database {circuit.database} is unreachable. Failover has been initiated.\"\n            )\n\n            self._bg_scheduler.run_once(","sourceCodeStart":396,"sourceCodeEnd":432,"githubUrl":"https://github.com/redis/redis-py/blob/6a6b581b48225afa0b76912d1028c6035baee932/redis/multidb/client.py#L396-L432","documentation":"Raised as InitialHealthCheckFailedError by MultiDBClient._perform_initial_health_check() (client.py:414) when the proportion of healthy databases after the initial check does not satisfy the configured initial_health_check_policy (ALL_AVAILABLE, MAJORITY_AVAILABLE, or ONE_AVAILABLE). The message interpolates the active policy so the caller can see which bar was missed.","triggerScenarios":"Constructing MultiDBClient and calling initialize() (or execute_command, which triggers initialize) when health-check results violate the policy: ALL_AVAILABLE with any unhealthy DB; MAJORITY_AVAILABLE with <= half healthy; ONE_AVAILABLE with none healthy.","commonSituations":"Partial fleet outage at boot (some regions down); ALL_AVAILABLE policy being too strict for geographically distributed fleets; one misconfigured endpoint dragging the majority check below 50%; network issues affecting a subset of databases.","solutions":["Inspect which databases failed (catch the error, then check each endpoint with redis-cli PING) and fix them.","If partial availability is acceptable, switch initial_health_check_policy to MAJORITY_AVAILABLE or ONE_AVAILABLE.","Defer client construction until enough databases are reachable (readiness gate).","Review health-check definitions and circuit-breaker thresholds to ensure they aren't too strict."],"exampleFix":"# before\nconfig.initial_health_check_policy = InitialHealthCheck.ALL_AVAILABLE\nclient = MultiDBClient(config)  # raises if any DB unhealthy\n\n# after\nconfig.initial_health_check_policy = InitialHealthCheck.MAJORITY_AVAILABLE\nclient = MultiDBClient(config)  # tolerates a minority of unhealthy DBs","handlingStrategy":"validation","validationCode":"# Pre-flight: probe each endpoint before constructing the client\nfrom redis.config import MultiDbConfig, InitialHealthCheck  # adjust import\n\nhealthy = probe_all_endpoints(config)  # your PING-based check\nif config.initial_health_check_policy == InitialHealthCheck.ALL_AVAILABLE and not all(healthy):\n    raise RuntimeError('not all endpoints healthy; ALL_AVAILABLE policy will fail')\nif config.initial_health_check_policy == InitialHealthCheck.MAJORITY_AVAILABLE and sum(healthy) <= len(healthy) / 2:\n    raise RuntimeError('no majority healthy; MAJORITY_AVAILABLE policy will fail')\nif config.initial_health_check_policy == InitialHealthCheck.ONE_AVAILABLE and not any(healthy):\n    raise RuntimeError('no endpoint healthy; ONE_AVAILABLE policy will fail')","typeGuard":"from redis.multidb.config import InitialHealthCheck\n\ndef policy_satisfied(policy, healthy_flags) -> bool:\n    if policy == InitialHealthCheck.ALL_AVAILABLE:\n        return all(healthy_flags)\n    if policy == InitialHealthCheck.MAJORITY_AVAILABLE:\n        return sum(healthy_flags) > len(healthy_flags) / 2\n    if policy == InitialHealthCheck.ONE_AVAILABLE:\n        return any(healthy_flags)\n    return False","tryCatchPattern":"from redis.multidb.exception import InitialHealthCheckFailedError\nimport time\n\nfor _ in range(30):\n    try:\n        client = MultiDBClient(config)\n        client.initialize()\n        break\n    except InitialHealthCheckFailedError:\n        time.sleep(3)\nelse:\n    # fall back to a more permissive policy\n    config.initial_health_check_policy = InitialHealthCheck.ONE_AVAILABLE\n    client = MultiDBClient(config)","preventionTips":["Match the policy to your availability requirements (ONE_AVAILABLE for max liveness).","Run a readiness probe over all endpoints before constructing the client.","Tune health checks so they don't mark slow-but-alive databases unhealthy."],"tags":["multidb","active-active","health-check","startup","policy"],"backgroundTag":null,"analyzedSha":"6a6b581b48225afa0b76912d1028c6035baee932","analyzedAt":"2026-08-10T12:52:44.840Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}