iflytek/astron-agent · error · ValueError

Invalid Redis address format

Error message

Invalid Redis address format: {cluster_addr}

What it means

init_redis_cluster() parses the Redis address with the regex r"([^:]+):(\d+)". When REDIS_CLUSTER_ADDR_KEY is unset it treats the whole address as a single host:port; if it does not match that pattern, ValueError is raised. Note: the cluster branch silently skips non-matching pairs instead of raising — this error only fires in single-node mode.

Solutions

1. Format the address as plain 'host:port', e.g. '127.0.0.1:6379' — strip any redis:// prefix.
2. If using a comma-separated cluster list, make sure the cluster-mode env var (const.REDIS_CLUSTER_ADDR_KEY) is set, otherwise only single-node parsing runs.
3. Validate the config value before constructing RedisService: split on ':' and check there are exactly 2 parts with a numeric port.
4. For IPv6 hosts use bracketed notation and adjust parsing, since the regex will mis-split colons.

Example fix

// before
RedisService("redis://127.0.0.1:6379", password=pwd)
RedisService("localhost", password=pwd)
// after
RedisService("127.0.0.1:6379", password=pwd)

import re
addr = os.environ["REDIS_ADDR"]
pairs = addr.split(",")
for p in pairs:
    if not re.fullmatch(r"[^:]+:\d+", p):
        raise ValueError(f"REDIS_ADDR must be host:port (comma-separated), got {p!r}")

try:
    redis_service = RedisService(cluster_addr, password=pwd)
except ValueError as e:
    logger.error("bad REDIS_ADDR %r — expected host:port without redis:// prefix", e)

When it happens

Trigger: Passing 'localhost' or 'myhost' with no :port; using a URL form like 'redis://host:6379' or 'host:6379,other:6380' while the cluster env var is unset (regex fails on 'redis://host:6379'); IPv6 addresses containing colons; trailing whitespace or protocol prefixes; empty string.

Common situations: Config/env var set to a redis:// URL copied from documentation; forgetting the port (assuming default 6379); leaving the cluster-mode env var unset while supplying a comma-separated cluster address list, so only the first pair is parsed and everything else is silently dropped.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Cannot convert size
• invalid DATABASE_MAX_IDLE_CONNS
• invalid DATABASE_MAX_OPEN_CONNS
• invalid SERVICE_PORT
• Invalid size expression

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/9fe8a9a7c0cbef63. Report an issue: GitHub.

Appendix: source

Thrown at core/plugin/link/domain/models/utils.py:285

        logger.debug("redis cluster init in progress")
        if os.getenv(const.REDIS_CLUSTER_ADDR_KEY):
            host_port_pairs = cluster_addr.split(",")
            cluster_nodes = []
            for pair in host_port_pairs:
                match = re.match(r"([^:]+):(\d+)", pair)
                if match:
                    host = match.group(1)
                    port = match.group(2)
                    cluster_nodes.append({"host": host, "port": port})
            return RedisCluster(startup_nodes=cluster_nodes, password=password)

        match = re.match(r"([^:]+):(\d+)", cluster_addr)
        if match:
            host = match.group(1)
            port = match.group(2)
            return redis.Redis(host=host, port=int(port), password=password)
        else:
            raise ValueError(f"Invalid Redis address format: {cluster_addr}")

    # check connection
    def is_connected(self) -> bool:
        """
        Check if the Redis client is connected.
        """
        try:
            self._client.ping()
            return True
        except redis.exceptions.ConnectionError:
            return False

    def get(self, key: str) -> Optional[Any]:
        """
        Retrieve an item from the cache.

        Args:
            key: The key of the item to retrieve.

View on GitHub (pinned to 5e758547a8)