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

#{@command.to_s.upcase} cannot be used in Redis::Distributed

Error message

#{@command.to_s.upcase} 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 "#{@command.to_s.upcase} 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:1527

    end

    def key_tag(key)
      key = key.to_s
      key[@tag, 1] if key.match?(@tag)
    end

    def ensure_same_node(command, keys)
      all = true

      tags = keys.map do |key|
        tag = key_tag(key)
        all = false unless tag
        tag
      end

      if (all && tags.uniq.size != 1) || (!all && keys.uniq.size != 1)
        # Not 1 unique tag or not 1 unique key
        raise CannotDistribute, command
      end

      yield(node_for(keys.first))
    end
  end
end

View on GitHub (pinned to 2ba9010b91)

Solutions

1. Do not call the reported command on Redis::Distributed; it involves multiple keys that must live on the same server.
2. Call the command on the specific node that owns the keys, or use Redis::Cluster where the server enforces slot co-location.

When it happens

Trigger: Thrown at lib/redis/distributed.rb:1527 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/06bbc83c3b059c22. Report an issue: GitHub.