{"record":{"id":"d88c82ba2fac3e73","repo":"vllm-project/vllm","slug":"actor-actor-not-found-in-communicator-group","errorCode":null,"errorMessage":"Actor {actor} not found in communicator group","messagePattern":"Actor (.+?) not found in communicator group","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/distributed/device_communicators/ray_communicator.py","lineNumber":144,"sourceCode":"\n    def get_actor_handles(self) -> list[\"ray.actor.ActorHandle\"]:\n        return self._actor_handles\n\n    def get_rank(self, actor: ray.actor.ActorHandle) -> int:\n        \"\"\"\n        Return the given actor's rank using device communicator collective ops.\n        \"\"\"\n        assert hasattr(self, \"_actor_id_to_rank\"), (\n            \"Actor rank mapping not built. \"\n            \"This should have been done during initialization.\"\n        )\n\n        actor_id_str = actor._actor_id.hex()\n\n        if actor_id_str in self._actor_id_to_rank:\n            return self._actor_id_to_rank[actor_id_str]  # type: ignore\n        else:\n            raise ValueError(f\"Actor {actor} not found in communicator group\")\n\n    def get_self_rank(self) -> int | None:\n        \"\"\"\n        Return this actor's rank.\n        \"\"\"\n        return self._rank\n\n    def get_world_size(self) -> int:\n        \"\"\"\n        Return the number of ranks in the RayPPCommunicator group.\n        \"\"\"\n        return self._world_size\n\n    def send(self, buf: \"torch.Tensor\", peer_rank: int) -> None:\n        \"\"\"\n        Send a torch.Tensor to a peer.\n\n        This returns when the send kernel has been queued, but the kernel may","sourceCodeStart":126,"sourceCodeEnd":162,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/device_communicators/ray_communicator.py#L126-L162","documentation":"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.","triggerScenarios":"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.","commonSituations":"Mixing handles from two RayPPCommunicator instances; autoscaling/restart replacing a Ray actor so its id no longer matches; stale handles captured before group construction.","solutions":["Ensure every actor you will query is included in the actor_handles list passed to the RayPPCommunicator constructor","Fetch handles from the same group object you constructed the communicator with","After actor restarts, rebuild the communicator and rank mapping"],"exampleFix":"# before\ncomm = RayPPCommunicator(world_size, rank, actor_handles=[a0, a1])\ncomm.get_rank(a2)  # a2 never registered -> ValueError\n\n# after\ncomm = RayPPCommunicator(world_size, rank, actor_handles=[a0, a1, a2])\ncomm.get_rank(a2)","handlingStrategy":"validation","validationCode":"known = {a._actor_id.hex() for a in actor_handles}\nassert actor._actor_id.hex() in known, \"actor not in this communicator's actor_handles; rebuild group or use a member handle\"","typeGuard":"def actor_in_group(actor, comm) -> bool:\n    return actor._actor_id.hex() in comm._actor_id_to_rank","tryCatchPattern":"try:\n    rank = comm.get_rank(actor)\nexcept ValueError:\n    raise RuntimeError(f\"{actor} was not registered; pass it in actor_handles at init\")","preventionTips":["Keep exactly one source of truth for actor handles","Rebuild communicator after actor restarts","Never mix handles across Ray jobs or groups"],"tags":["ray","pipeline-parallel","distributed","actor-management"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}