redis/redis-py · error · ValueError

Database health check url is not set. Please check…

Error message

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

What it means

Raised as a ValueError inside LagAwareHealthCheck.check_health when the DatabaseConfig for the current database has health_check_url set to None. The lag-aware health check queries the Redis Enterprise REST API to measure replication lag, so it needs an explicit REST API base URL to talk to. Without that URL there is no endpoint to probe, so the check refuses to run.

Solutions

1. Set DatabaseConfig.health_check_url to the Redis Enterprise REST API base URL (e.g. https://cluster-host) before starting the health check.
2. If you are not on Redis Enterprise, switch to a non-lag-aware health check class that does not require the REST API.
3. Verify the multidb config loader actually populates health_check_url from your environment or discovery response.

Example fix

# before
db = DatabaseConfig(client=client, health_check_url=None)
await lag_hc.check_health(db, client)
# after
db = DatabaseConfig(client=client, health_check_url="https://enterprise-cluster-host")
await lag_hc.check_health(db, client)

if getattr(database, "health_check_url", None) is None:
    raise ValueError("health_check_url not configured; cannot run LagAwareHealthCheck")
await lag_hc.check_health(database, client)

def has_health_check_url(db) -> bool:
    return getattr(db, "health_check_url", None) is not None

try:
    await lag_hc.check_health(database, client)
except ValueError as e:
    if "health check url" in str(e):
        logger.error("Lag health check skipped: %s", e)
    else:
        raise

When it happens

Trigger: Calling check_health() on a LagAwareHealthCheck instance whose database entry has database.health_check_url == None. This happens when the DatabaseConfig was constructed without passing a health_check_url (e.g. a multidb client built from plain Redis URIs instead of Redis Enterprise REST API metadata).

Common situations: Pointing the multidb client at a standalone Redis or Redis Cloud non-Enterprise deployment that does not expose the /v1 REST API. Forgetting to set health_check_url when programmatically assembling DatabaseConfig objects. Migrating from a simpler health check to LagAwareHealthCheck without updating the config builder.

Related errors

• Could not find a matching bdb
• Cannot set active database, database is unhealthy
• Cannot set active database, database is unhealthy
• Cluster client has no nodes - cannot create health check…
• health_check_probes must be greater than 0

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

Appendix: 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 6a6b581b48)