redis/redis-py · error · ValueError

health_check_probes must be greater than 0

Error message

health_check_probes must be greater than 0

What it means

Raised as ValueError by AbstractHealthCheck.__init__ (healthcheck.py:356-357) when the health_check_probes parameter is less than 1. A probe count of zero would make the health-check loops (HealthyAllPolicy/HealthyMajorityPolicy/HealthyAnyPolicy._execute) run zero iterations and report misleading health, so it is rejected at construction.

Solutions

1. Set health_check_probes to at least 1 (the default DEFAULT_HEALTH_CHECK_PROBES is 3).
2. Validate the value before constructing the health check: probes = max(1, int(value)).
3. If you intended to disable health checks, do not set probes=0 — instead exclude the health check or reconfigure policy.
4. Audit config sources (env vars, YAML) for a probes/health_check_probes key that can resolve to 0.

Example fix

// before
hc = PingHealthCheck(health_check_probes=0)  # ValueError

// after
probes = max(1, int(os.environ.get("HEALTH_CHECK_PROBES", "3")))
hc = PingHealthCheck(health_check_probes=probes)

def valid_probe_count(n) -> bool:
    return isinstance(n, int) and n >= 1

probes = int(os.environ.get("HEALTH_CHECK_PROBES", "3"))
if not valid_probe_count(probes):
    raise ValueError(f"health_check_probes must be >= 1, got {probes}")

hc = PingHealthCheck(health_check_probes=probes)

def is_positive_int(n) -> bool:
    return isinstance(n, int) and not isinstance(n, bool) and n >= 1

try:
    hc = PingHealthCheck(health_check_probes=probes)
except ValueError as e:
    if "health_check_probes must be greater than 0" in str(e):
        probes = max(1, int(probes) if probes else 3)
        hc = PingHealthCheck(health_check_probes=probes)
    else:
        raise

When it happens

Trigger: Constructing PingHealthCheck(health_check_probes=0), LagAwareHealthCheck(health_check_probes=0), any AbstractHealthCheck subclass with probes=0, or setting MultiDbConfig.health_check_probes=0 (which is forwarded into the default PingHealthCheck). Negative values are equally rejected.

Common situations: Driving probes from an env var/config that defaulted to 0, computing probes from a formula that can hit zero (e.g. max(0, x)), misreading the parameter as a threshold rather than a count, or test fixtures that pass 0 to 'disable' probes.

Related errors

• Cluster client has no nodes - cannot create health check…
• Unsupported client type
• Cannot set active database, database is unhealthy
• Given database is not a member of database list
• Initial connection failed - no active database found

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

Appendix: source

Thrown at redis/asyncio/multidb/healthcheck.py:357

class HealthCheckPolicies(Enum):
    HEALTHY_ALL = HealthyAllPolicy
    HEALTHY_MAJORITY = HealthyMajorityPolicy
    HEALTHY_ANY = HealthyAnyPolicy


DEFAULT_HEALTH_CHECK_POLICY: HealthCheckPolicies = HealthCheckPolicies.HEALTHY_ALL


class AbstractHealthCheck(HealthCheck):
    def __init__(
        self,
        health_check_probes: int = DEFAULT_HEALTH_CHECK_PROBES,
        health_check_delay: float = DEFAULT_HEALTH_CHECK_DELAY,
        health_check_timeout: float = DEFAULT_HEALTH_CHECK_TIMEOUT,
    ):
        if health_check_probes < 1:
            raise ValueError("health_check_probes must be greater than 0")
        self._health_check_probes = health_check_probes
        self._health_check_delay = health_check_delay
        self._health_check_timeout = health_check_timeout

    @property
    def health_check_probes(self) -> int:
        return self._health_check_probes

    @property
    def health_check_delay(self) -> float:
        return self._health_check_delay

    @property
    def health_check_timeout(self) -> float:
        return self._health_check_timeout

    @abstractmethod
    async def check_health(self, database, hc_client: AsyncRedisClientT) -> bool:

View on GitHub (pinned to 6a6b581b48)