vllm-project/vllm · error · ValueError

torch_profiler_dir must be set when profiler is 'torch'

Error message

torch_profiler_dir must be set when profiler is 'torch'

What it means

Inverse pairing rule: when profiler == 'torch', ProfilerConfig requires torch_profiler_dir to be set, because both the frontend (AsyncLLM) and workers need a directory to write trace files. An absolute-path expansion is applied afterwards (URI schemes like gs:// pass through untouched).

Source

Thrown at vllm/config/profiler.py:182

        hash_str = safe_hash(str(factors).encode(), usedforsecurity=False).hexdigest()
        return hash_str

    @model_validator(mode="after")
    def _validate_profiler_config(self) -> Self:
        has_delay_or_limit = self.delay_iterations > 0 or self.max_iterations > 0
        if self.profiler == "torch" and has_delay_or_limit and not self.ignore_frontend:
            logger.warning_once(
                "Using 'torch' profiler with delay_iterations or max_iterations "
                "while ignore_frontend is False may result in high overhead."
            )

        torch_profiler_dir = self.torch_profiler_dir
        if torch_profiler_dir and self.profiler != "torch":
            raise ValueError(
                "torch_profiler_dir is only applicable when profiler is set to 'torch'"
            )
        if self.profiler == "torch" and not torch_profiler_dir:
            raise ValueError("torch_profiler_dir must be set when profiler is 'torch'")

        # Support any URI scheme (gs://, s3://, hdfs://, etc.)
        # These paths should not be converted to absolute paths
        if torch_profiler_dir and not _is_uri_path(torch_profiler_dir):
            self.torch_profiler_dir = os.path.abspath(
                os.path.expanduser(torch_profiler_dir)
            )

        proton_profiler_dir = self.proton_profiler_dir
        non_default_proton_options = [
            name
            for name, value, default in (
                ("proton_profiler_dir", proton_profiler_dir, ""),
                ("proton_context", self.proton_context, "shadow"),
                ("proton_data", self.proton_data, "tree"),
                ("proton_backend", self.proton_backend, None),
                ("proton_mode", self.proton_mode, None),
                ("proton_hook", self.proton_hook, None),

View on GitHub (pinned to c794754062)

Solutions

1. Add torch_profiler_dir: --profiler-config profiler=torch,torch_profiler_dir=/tmp/vllm_traces.
2. Use an absolute local path, or a URI (gs://bucket/traces) if uploading remotely.

Example fix

# before
ProfilerConfig(profiler='torch')

# after
ProfilerConfig(profiler='torch', torch_profiler_dir='/tmp/vllm_traces')

def validate_profiler_cfg(profiler: str | None, torch_dir: str) -> None:
    if profiler == "torch" and not torch_dir:
        raise SystemExit("profiler='torch' requires torch_profiler_dir")

When it happens

Trigger: Passing profiler='torch' without torch_profiler_dir, e.g. --profiler-config profiler=torch alone.

Common situations: Assuming the torch profiler writes to CWD by default; enabling the profiler through the /start_profile endpoint without configuring an output dir first.

Related errors

• torch_profiler_dir is only applicable when profiler is set t
• Unable to use nsight profiling unless workers run with Ray.
• {options} only applicable when profiler is set to 'proton'
• proton_profiler_dir must be set when profiler is 'proton'
• proton_profiler_dir must be a local directory

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