redis/redis-py · error · ValueError

Subcommand {subcommand_name} not found in command {command_n

Error message

Subcommand {subcommand_name} not found in command {command_name}

What it means

Raised by CommandsParser._is_keyless_command() when a subcommand_name is supplied (e.g. 'CLUSTER|NODES') but no entry in command['subcommands'] matches that 'parent|child' string. The method walks the COMMAND-supplied subcommand list and raises ValueError naming both the missing subcommand and its parent. This is a programmer/server-metadata error, not a network error.

Source

Thrown at redis/_parsers/commands.py:245

                The name of the subcommand to check, if applicable. If not provided,
                the check is performed only on the command.

        Returns:
            bool
                True if the specified command or subcommand is considered keyless,
                False otherwise.

        Raises:
            ValueError
                If the specified subcommand is not found within the command or the
                specified command does not exist in the available commands.
        """
        if subcommand_name:
            for subcommand in self.commands.get(command_name)["subcommands"]:
                if str_if_bytes(subcommand[0]) == subcommand_name:
                    parsed_subcmd = self.parse_subcommand(subcommand)
                    return parsed_subcmd["first_key_pos"] <= 0
            raise ValueError(
                f"Subcommand {subcommand_name} not found in command {command_name}"
            )
        else:
            command_details = self.commands.get(command_name, None)
            if command_details is not None:
                return command_details["first_key_pos"] <= 0

            raise ValueError(f"Command {command_name} not found in commands")

    def get_command_policies(self) -> PolicyRecords:
        """
        Retrieve and process the command policies for all commands and subcommands.

        This method traverses through commands and subcommands, extracting policy details
        from associated data structures and constructing a dictionary of commands with their
        associated policies. It supports nested data structures and handles both main commands
        and their subcommands.

View on GitHub (pinned to da03cdc7e8)

Solutions

Upgrade redis-py to a release that knows the subcommands your Redis version emits.
Confirm the subcommand actually exists via 'redis-cli COMMAND INFO <parent>'.
If you call _is_keyless_command directly, validate subcommand_name against the command's subcommand list first.
Report the subcommand string in the error to the maintainers so the parser table can be extended.

Example fix

// before
parser._is_keyless_command("cluster", "BOGUS")  # ValueError

// after
valid = [str_if_bytes(s[0]) for s in parser.commands["cluster"]["subcommands"]]
if "cluster|BOGUS" not in valid:
    raise KeyError(f"unknown subcommand; valid: {valid}")

Defensive patterns

Strategy: validation

Validate before calling

# Validate subcommand against the parser's known list before calling
def assert_subcommand_known(parser, parent, sub):
    subs = parser.commands.get(parent, {}).get("subcommands") or []
    names = [s[0].decode() if isinstance(s[0], bytes) else s[0] for s in subs]
    if f"{parent}|{sub.upper()}" not in names:
        raise KeyError(f"unknown subcommand; valid: {names}")

Try / catch

try:
    parser._is_keyless_command("cluster", sub)
except ValueError as e:
    if "Subcommand" in str(e):
        # unknown subcommand; do not retry, fix the name or upgrade client
        raise

Prevention

Upgrade redis-py alongside Redis upgrades so subcommand tables stay in sync.
Validate subcommand names against COMMAND INFO output before custom routing.
Avoid calling private _is_keyless_command directly; use the public cluster API.
Report missing subcommand strings upstream so the parser table grows.

When it happens

Trigger: Cluster client building command policies at startup (get_command_policies) when COMMAND reports a parent command with subcommands but the specific 'parent|child' token the parser built is absent - e.g. a new subcommand the parser does not yet know, or a renamed/custom subcommand. Also triggered by passing a fabricated subcommand name in custom routing code.

Common situations: Upgrading Redis to a version that added/renamed subcommands while running an older redis-py; running a Redis fork that emits non-standard subcommand names; manually invoking _is_keyless_command with an unvalidated subcommand.

Related errors

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