redis/redis-py · error · DataError

MIGRATE requires at least one key

Error message

MIGRATE requires at least one key

What it means

Raised by migrate when the keys argument resolves to an empty list. migrate accepts keys as either a single key or a list (via list_or_args), and after flattening it checks that at least one key remains. Migrating zero keys is a protocol error on the server, so the client rejects it early.

Source

Thrown at redis/commands/core.py:1836

        The ``timeout``, specified in milliseconds, indicates the maximum
        time the connection between the two servers can be idle before the
        command is interrupted.

        If ``copy`` is True, the specified ``keys`` are NOT deleted from
        the source server.

        If ``replace`` is True, this operation will overwrite the keys
        on the destination server if they exist.

        If ``auth`` is specified, authenticate to the destination server with
        the password provided.

        For more information, see https://redis.io/commands/migrate
        """
        keys = list_or_args(keys, [])
        if not keys:
            raise DataError("MIGRATE requires at least one key")
        pieces = []
        if copy:
            pieces.append(b"COPY")
        if replace:
            pieces.append(b"REPLACE")
        if auth:
            pieces.append(b"AUTH")
            pieces.append(auth)
        pieces.append(b"KEYS")
        pieces.extend(keys)
        return self.execute_command(
            "MIGRATE", host, port, "", destination_db, timeout, *pieces, **kwargs
        )

    @overload
    def object(self: SyncClientProtocol, infotype: str, key: KeyT, **kwargs) -> Any: ...

    @overload

View on GitHub (pinned to da03cdc7e8)

Solutions

1. Ensure the keys collection is non-empty before calling migrate.
2. Guard dynamic key lists: if not keys: skip or log instead of migrating.
3. If migrating a single key, pass it directly or as a one-element list.

Example fix

# before
r.migrate('host', 6379, selected_keys, 0, 5000)  # selected_keys is []
# after
if selected_keys:
    r.migrate('host', 6379, selected_keys, 0, 5000)

from redis.helpers import list_or_args
keys = list_or_args(keys, [])
if not keys:
    raise ValueError('migrate requires at least one key')

When it happens

Trigger: Calling r.migrate('host', 6379, [], 0, 5000) with an empty list. Passing keys=[] from a dynamic query that returned no results. Passing keys as a single empty string.

Common situations: Batch-migrating keys selected by a SCAN query that matched nothing. Conditional migration where the key set is empty at runtime. Passing an empty list as a placeholder.

Related errors

• CLIENT KILL type must be one of {client_types!r}
• CLIENT KILL skipme must be a bool
• CLIENT KILL <filter> <value> ... ... <filter> <value> must s
• CLIENT LIST _type must be one of {client_types!r}
• client_id must be a list

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