redis/redis-py · error · ValueError

Could not find a matching bdb

Error message

Could not find a matching bdb

What it means

Raised by LagAwareHealthCheck.check_health (redis/asyncio/multidb/healthcheck.py:499) after querying /v1/bdbs on the Redis Enterprise REST API and finding no database (bdb) whose endpoint dns_name or addr matches the host the client is connected to. The client's configured host and the cluster's registered endpoints disagree.

Source

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

        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
                    break

                # In case if the host was set as public IP
                for addr in endpoint["addr"]:
                    if addr == db_host:
                        matching_bdb = bdb
                        break

        if matching_bdb is None:
            logger.warning("LagAwareHealthCheck failed: Couldn't find a matching bdb")
            raise ValueError("Could not find a matching bdb")

        url = (
            f"/v1/bdbs/{matching_bdb['uid']}/availability"
            f"?extend_check=lag&availability_lag_tolerance_ms={self._lag_aware_tolerance}"
        )
        await self._http_client.get(url, expect_json=False)

        # Status checked in an http client, otherwise HttpError will be raised
        return True

View on GitHub (pinned to da03cdc7e8)

Solutions

1. Make the client's host exactly match a dns_name (or an addr entry) reported by GET /v1/bdbs on the same REST API.
2. Query /v1/bdbs yourself and set the DatabaseConfig client host to a registered endpoint.
3. Confirm health_check_url and the client host refer to the same Redis Enterprise cluster.

Example fix

# before
client = AsyncRedis(host="public-lb.example.com", port=12000)
# no bdb endpoint matches 'public-lb.example.com'
# after
client = AsyncRedis(host="us1-db1.rec.local", port=12000)  # matches bdb endpoint dns_name

bdbs = await http.get(f'{base_url}/v1/bdbs')
known_hosts = {ep['dns_name'] for b in bdbs for ep in b['endpoints']} | {a for b in bdbs for ep in b['endpoints'] for a in ep['addr']}
assert client_host in known_hosts, f'{client_host} not registered as a bdb endpoint'

def host_matches_bdb(host: str, bdbs: list) -> bool:
    return any(host == ep.get('dns_name') or host in ep.get('addr', []) for b in bdbs for ep in b.get('endpoints', []))

try:
    await lag_hc.check_health(database, client)
except ValueError as e:
    logger.warning('bdb match failed for %s: %s', client_host, e)
    raise

When it happens

Trigger: Client connected to an IP/hostname that is not registered as an endpoint dns_name or addr on any bdb in the Enterprise cluster; using a load-balancer or public IP not listed in the cluster's bdb endpoints; stale cluster state after a migration.

Common situations: Connecting through an external LB/FQDN while the REST API only knows internal endpoint names; pointing the client at the wrong cluster than the one the REST API is queried against; DNS drift after failover.

Related errors

• Database health check url is not set. Please check DatabaseC
• 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/857963c7f5d1c0fb.json. Report an issue: GitHub.