vllm-project/vllm · error · ValueError

Actor {actor} not found in communicator group

Error message

Actor {actor} not found in communicator group

What it means

RayPPCommunicator.build_rank / get_rank resolves an actor's rank via the _actor_id_to_rank mapping built during initialization from the actor_handles list. If the queried actor's _actor_id.hex() is not a key in that mapping, it raises ValueError('Actor ... not found in communicator group') — the actor simply was not part of the group this communicator was constructed with.

Source

Thrown at vllm/distributed/device_communicators/ray_communicator.py:144

    def get_actor_handles(self) -> list["ray.actor.ActorHandle"]:
        return self._actor_handles

    def get_rank(self, actor: ray.actor.ActorHandle) -> int:
        """
        Return the given actor's rank using device communicator collective ops.
        """
        assert hasattr(self, "_actor_id_to_rank"), (
            "Actor rank mapping not built. "
            "This should have been done during initialization."
        )

        actor_id_str = actor._actor_id.hex()

        if actor_id_str in self._actor_id_to_rank:
            return self._actor_id_to_rank[actor_id_str]  # type: ignore
        else:
            raise ValueError(f"Actor {actor} not found in communicator group")

    def get_self_rank(self) -> int | None:
        """
        Return this actor's rank.
        """
        return self._rank

    def get_world_size(self) -> int:
        """
        Return the number of ranks in the RayPPCommunicator group.
        """
        return self._world_size

    def send(self, buf: "torch.Tensor", peer_rank: int) -> None:
        """
        Send a torch.Tensor to a peer.

        This returns when the send kernel has been queued, but the kernel may

View on GitHub (pinned to c794754062)

Solutions

  1. Ensure every actor you will query is included in the actor_handles list passed to the RayPPCommunicator constructor
  2. Fetch handles from the same group object you constructed the communicator with
  3. After actor restarts, rebuild the communicator and rank mapping

Example fix

# before
comm = RayPPCommunicator(world_size, rank, actor_handles=[a0, a1])
comm.get_rank(a2)  # a2 never registered -> ValueError

# after
comm = RayPPCommunicator(world_size, rank, actor_handles=[a0, a1, a2])
comm.get_rank(a2)
Defensive patterns

Strategy: validation

Validate before calling

known = {a._actor_id.hex() for a in actor_handles}
assert actor._actor_id.hex() in known, "actor not in this communicator's actor_handles; rebuild group or use a member handle"

Type guard

def actor_in_group(actor, comm) -> bool:
    return actor._actor_id.hex() in comm._actor_id_to_rank

Try / catch

try:
    rank = comm.get_rank(actor)
except ValueError:
    raise RuntimeError(f"{actor} was not registered; pass it in actor_handles at init")

Prevention

When it happens

Trigger: Calling get_rank(actor) with an actor handle obtained from a different Ray job/actor group; querying after the group membership changed; passing a re-created actor (new actor id) whose handle was not among the actor_handles used at init.

Common situations: Mixing handles from two RayPPCommunicator instances; autoscaling/restart replacing a Ray actor so its id no longer matches; stale handles captured before group construction.

Related errors

AI-assisted analysis of vllm-project/vllm@c794754062 (2026-08-14). Data as JSON: /api/errors/d88c82ba2fac3e73. Report an issue: GitHub.