redis/redis-py · error · ValueError

Wrong command or module name: {command_name}

Error message

Wrong command or module name: {command_name}

What it means

Raised by the sync BasePolicyResolver.resolve() when command_name, split on '.', yields more than two parts. The cluster policy resolver expects either 'COMMAND' (resolved to 'core.COMMAND') or 'module.COMMAND'. Three or more dots means a malformed command name. This is internal infrastructure used by RedisCluster for routing; application code rarely constructs these names directly.

Source

Thrown at redis/commands/policies.py:199

        pass


class BasePolicyResolver(PolicyResolver):
    """
    Base class for policy resolvers.
    """

    def __init__(
        self, policies: PolicyRecords, fallback: Optional[PolicyResolver] = None
    ) -> None:
        self._policies = policies
        self._fallback = fallback

    def resolve(self, command_name: str) -> Optional[CommandPolicies]:
        parts = command_name.split(".")

        if len(parts) > 2:
            raise ValueError(f"Wrong command or module name: {command_name}")

        module, command = parts if len(parts) == 2 else ("core", parts[0])

        if self._policies.get(module, None) is None:
            if self._fallback is not None:
                return self._fallback.resolve(command_name)
            else:
                return None

        if self._policies.get(module).get(command, None) is None:
            if self._fallback is not None:
                return self._fallback.resolve(command_name)
            else:
                return None

        return self._policies.get(module).get(command)

    @abstractmethod

View on GitHub (pinned to da03cdc7e8)

Solutions

1. Ensure command_name has at most one dot: 'module.COMMAND' or 'COMMAND'.
2. If a module name legitimately contains a dot, alias/escape it before resolution.
3. Update the policy table / CommandsParser to expose the command under a single-dot name.

Example fix

// before
policies.resolve('json.set.extra')
// after
policies.resolve('json.set')

def safe_resolve(resolver, command_name):
    parts = command_name.split(".")
    if len(parts) > 2:
        raise ValueError(
            f"command_name must have at most one dot, got {command_name!r}"
        )
    return resolver.resolve(command_name)

def is_valid_command_name(name) -> bool:
    return isinstance(name, str) and name.count(".") <= 1 and len(name) > 0

try:
    resolver.resolve(command_name)
except ValueError as e:
    if "Wrong command or module name" in str(e):
        command_name = command_name.rsplit(".", 1)[-1]  # last segment
        resolver.resolve(command_name)
    else:
        raise

When it happens

Trigger: A custom command or module command is registered with a dotted name containing more than one dot, e.g. 'json.set.extra' or 'a.b.c'; the resolver is invoked via the cluster client's command path with such a name.

Common situations: Integrating a module whose name itself contains a dot; mis-joining module + command with an extra separator; incorrect STATIC_POLICIES registration for a new module command.

Related errors

• Incorrect request policy type: {policy_type}
• Incorrect response policy type: {policy_type}
• {cmd_name.upper()} command doesn't exist in Redis commands
• Subcommand {subcommand_name} not found in command {command_n
• Command {command_name} not found in commands

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