vllm-project/vllm · error · ValueError

Unable to use nsight profiling unless workers run with Ray.

Error message

Unable to use nsight profiling unless workers run with Ray.

What it means

ParallelConfig raises this when ray_workers_use_nsight is enabled but the deployment is not using Ray. Nsight worker profiling is implemented by injecting nsight commands into Ray worker processes, so it depends on the Ray executor to propagate profiling to each worker.

Source

Thrown at vllm/config/parallel.py:1032

            raise ValueError(
                "Unrecognized distributed executor backend "
                f"{self.distributed_executor_backend}. Supported "
                "values are 'ray', 'mp' 'uni', 'external_launcher', "
                " custom Executor subclass or its import path."
            )
        if self.use_ray:
            from vllm.v1.executor import ray_utils

            ray_utils.assert_ray_available()

        if not current_platform.use_custom_allreduce():
            self.disable_custom_all_reduce = True
            logger.debug(
                "Disabled the custom all-reduce kernel because it is not "
                "supported on current platform."
            )
        if self.ray_workers_use_nsight and not self.use_ray:
            raise ValueError(
                "Unable to use nsight profiling unless workers run with Ray."
            )

        return self

    def reconfigure_for_independent_dp_rank(self) -> None:
        """Reconfigure for a single independent non-MoE DP rank."""
        # Capture these before changing DP fields.
        nnodes = self.nnodes_within_dp
        node_rank = self.node_rank_within_dp
        self.data_parallel_size = 1
        self.data_parallel_size_local = 1
        self.data_parallel_rank = 0
        self.nnodes = nnodes
        self.node_rank = node_rank

View on GitHub (pinned to c794754062)

Solutions

1. Remove --ray-workers-use-nsight, or set ray_workers_use_nsight=False.
2. If you need nsight with Ray, also pass --distributed-executor-backend ray.
3. For non-Ray profiling, use the torch profiler config instead (profiler='torch' with torch_profiler_dir).

Example fix

# before
vllm serve model --ray-workers-use-nsight --distributed-executor-backend mp

# after
vllm serve model --distributed-executor-backend ray --ray-workers-use-nsight

def validate_nsight(use_nsight: bool, use_ray: bool) -> None:
    if use_nsight and not use_ray:
        raise SystemExit("--ray-workers-use-nsight requires --distributed-executor-backend ray")

When it happens

Trigger: Passing --ray-workers-use-nsight (or ray_workers_use_nsight=True in config) while distributed_executor_backend is anything other than ray, or while use_ray is False.

Common situations: Copying a profiling recipe from a Ray-based vLLM deployment into a local single-node mp/uni launch; leaving the flag on in a config file when switching executors.

Related errors

• nnodes > 1 can only be set when distributed executor backend
• torch_profiler_dir is only applicable when profiler is set t
• torch_profiler_dir must be set when profiler is 'torch'
• {options} only applicable when profiler is set to 'proton'
• proton_profiler_dir must be set when profiler is 'proton'

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