redis/redis-py · error · ValueError

Database health check url is not set. Please check DatabaseC

Error message

Database health check url is not set. Please check DatabaseConfig for the current database.

What it means

Raised by LagAwareHealthCheck.check_health (redis/asyncio/multidb/healthcheck.py:470) when database.health_check_url is None. The lag-aware policy queries the Redis Enterprise REST API at that URL, so an unset URL makes the check impossible. This is a configuration defect in the DatabaseConfig, not a runtime network failure.

Source

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

        )
        self._rest_api_port = rest_api_port
        self._lag_aware_tolerance = lag_aware_tolerance
        super().__init__(
            health_check_probes=health_check_probes,
            health_check_delay=health_check_delay,
            health_check_timeout=health_check_timeout,
        )

    async def check_health(self, database, hc_client: AsyncRedisClientT) -> bool:
        """
        Check database health via Redis Enterprise REST API.

        Note: The client parameter is not used for this health check as it
        relies on the REST API instead of Redis protocol. The client is
        accepted for interface compatibility.
        """
        if database.health_check_url is None:
            raise ValueError(
                "Database health check url is not set. Please check DatabaseConfig for the current database."
            )

        if isinstance(database.client, (AsyncRedis, SyncRedis)):
            db_host = database.client.get_connection_kwargs()["host"]
        else:
            # Cluster client
            db_host = database.client.get_nodes()[0].host

        base_url = f"{database.health_check_url}:{self._rest_api_port}"
        self._http_client.client.base_url = base_url

        # Find bdb matching to the current database host
        matching_bdb = None
        for bdb in await self._http_client.get("/v1/bdbs"):
            for endpoint in bdb["endpoints"]:
                if endpoint["dns_name"] == db_host:
                    matching_bdb = bdb

View on GitHub (pinned to da03cdc7e8)

Solutions

1. Set health_check_url on the DatabaseConfig to the Redis Enterprise REST API base URL (e.g. https://cluster-host).
2. If the target is not Redis Enterprise, switch to PingHealthCheck which uses the Redis protocol and needs no URL.
3. Audit every DatabaseConfig paired with a LagAwareHealthCheck to confirm health_check_url is populated.

Example fix

# before
db = DatabaseConfig(client=..., health_check_policy=HealthCheckPolicies.HEALTHY_ALL)
# health_check_url omitted -> LagAwareHealthCheck fails
# after
db = DatabaseConfig(client=..., health_check_url="https://rec-cluster.example.com")

if isinstance(hc, LagAwareHealthCheck) and not getattr(db_config, 'health_check_url', None):
    raise ConfigError('LagAwareHealthCheck requires DatabaseConfig.health_check_url')

def needs_rest_url(policy) -> bool:
    from redis.asyncio.multidb.healthcheck import LagAwareHealthCheck, HealthCheckPolicies
    cls = policy.value if isinstance(policy, HealthCheckPolicies) else policy
    return isinstance(cls, type) and issubclass(cls, LagAwareHealthCheck)

try:
    await health_check.check_health(database, client)
except ValueError as e:
    logger.error('health check misconfigured: %s', e)
    mark_database_unhealthy(database)

When it happens

Trigger: Configuring a multidb database with the LagAwareHealthCheck policy but omitting health_check_url on its DatabaseConfig; reusing a DatabaseConfig built for PingHealthCheck (which needs no URL) against a LagAwareHealthCheck.

Common situations: Mixing health-check policies across databases without updating each DatabaseConfig; pointing a LagAwareHealthCheck at a standalone (non-Enterprise) Redis that has no REST API URL.

Related errors

• Could not find a matching bdb
• health_check_probes must be greater than 0
• Hiredis is not installed
• Maintenance notifications are only supported with hiredis an
• 'username' and 'password' cannot be passed along with 'crede

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