redis/redis-rb · error · Redis::Distributed::CannotDistribute

MIGRATE cannot be used in Redis::Distributed because the key

Error message

MIGRATE cannot be used in Redis::Distributed because the keys involved need to be on the same server or because we cannot guarantee that the operation will be atomic.

What it means

Error "MIGRATE cannot be used in Redis::Distributed because the keys involved need to be on the same server or because we cannot guarantee that the operation will be atomic." thrown in redis/redis-rb.

Source

Thrown at lib/redis/distributed.rb:184

    # Get the time to live (in milliseconds) for a key.
    def pttl(key)
      node_for(key).pttl(key)
    end

    # Return a serialized version of the value stored at a key.
    def dump(key)
      node_for(key).dump(key)
    end

    # Create a key using the serialized value, previously obtained using DUMP.
    def restore(key, ttl, serialized_value, **options)
      node_for(key).restore(key, ttl, serialized_value, **options)
    end

    # Transfer a key from the connected instance to another instance.
    def migrate(_key, _options)
      raise CannotDistribute, :migrate
    end

    # Delete a key.
    def del(*args)
      args.flatten!(1)
      keys_per_node = args.group_by { |key| node_for(key) }
      keys_per_node.inject(0) do |sum, (node, keys)|
        sum + node.del(*keys)
      end
    end

    # Unlink keys.
    def unlink(*args)
      args.flatten!(1)
      keys_per_node = args.group_by { |key| node_for(key) }
      keys_per_node.inject(0) do |sum, (node, keys)|
        sum + node.unlink(*keys)
      end

View on GitHub (pinned to 2ba9010b91)

Solutions

1. Do not use migrate on Redis::Distributed; MIGRATE moves keys between servers which breaks client-side sharding assumptions.
2. Migrate keys manually by reading from the source node and writing to the target node.

When it happens

Trigger: Thrown at lib/redis/distributed.rb:184 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of redis/redis-rb@2ba9010b91 (2026-08-23). Data as JSON: /api/errors/8dc5be91b3c42006. Report an issue: GitHub.