redis/redis-py · error · ValueError

Wrong command or module name

Error message

Wrong command or module name: {command_name}

What it means

Raised by BasePolicyResolver.resolve() (redis/commands/policies.py:199) as a ValueError when the command_name string splits on '.' into more than 2 parts. The resolver expects either 'COMMAND' (resolved to core.COMMAND) or 'module.COMMAND'; anything with two or more dots (e.g. 'search.ft.aggregate') is malformed. This is an internal cluster-routing API, not normally called by end users.

Solutions

1. Use command names with at most one dot: 'COMMAND' or 'module.COMMAND'.
2. Strip extra namespace segments before resolving.
3. If you extended the cluster client with a new command, register it under a single module prefix.

Example fix

# before
resolver.resolve('search.ft.aggregate')
# after
resolver.resolve('search.aggregate')

def safe_resolve_name(command_name):
    if command_name.count('.') > 1:
        raise ValueError(f'command name must have at most one dot: {command_name}')
    return command_name

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

try:
    resolver.resolve(name)
except ValueError as e:
    if 'Wrong command' in str(e):
        # strip extra namespace segments and retry
        resolver.resolve(name.split('.')[-1])
    else:
        raise

When it happens

Trigger: Internally calling resolver.resolve('a.b.c') or any command name with >= 2 dots. Happens when a command name is mis-constructed with extra namespace segments, or a module command is double-prefixed.

Common situations: Custom policy resolvers, registering a command under a nested module path, or a typo concatenating module prefixes. End users typically only see this if they extend cluster routing or pass malformed command names to internal APIs.

Related errors

• Command not found in commands
• Subcommand not found in command
• At least a command with a key is needed to identify a node
• Cannot execute FT.CURSOR commands without FT.AGGREGATE
• Cannot identify slot number for command

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

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