What causes "proton_profiler_dir must be a local directory" in vllm-project/vllm?

Point proton_profiler_dir at a local directory (e.g. /tmp/proton).

vllm-project/vllm · error · ValueError

proton_profiler_dir must be a local directory

Error message

proton_profiler_dir must be a local directory

What it means

ProfilerConfig rejects proton_profiler_dir values that look like URIs (contain scheme:// with a multi-character scheme, e.g. gs://, s3://). Unlike torch traces, proton profiles must be written to a local directory because the proton tooling writes rank-qualified files directly; the config expands the path to an absolute local path afterwards.

Source

Thrown at vllm/config/profiler.py:216

                ("proton_backend", self.proton_backend, None),
                ("proton_mode", self.proton_mode, None),
                ("proton_hook", self.proton_hook, None),
                ("proton_output_format", self.proton_output_format, None),
            )
            if value != default
        ]
        if self.profiler != "proton" and non_default_proton_options:
            options = ", ".join(non_default_proton_options)
            raise ValueError(
                f"{options} only applicable when profiler is set to 'proton'"
            )
        if self.profiler == "proton" and not proton_profiler_dir:
            raise ValueError(
                "proton_profiler_dir must be set when profiler is 'proton'"
            )
        if proton_profiler_dir:
            if _is_uri_path(proton_profiler_dir):
                raise ValueError("proton_profiler_dir must be a local directory")
            self.proton_profiler_dir = os.path.abspath(
                os.path.expanduser(proton_profiler_dir)
            )

        if self.profiler == "proton":
            output_format = self.proton_output_format
            if output_format == "chrome_trace" and self.proton_data != "trace":
                raise ValueError("chrome_trace output requires proton_data='trace'")
            if (
                output_format in ("hatchet", "hatchet_msgpack")
                and self.proton_data != "tree"
            ):
                raise ValueError(f"{output_format} output requires proton_data='tree'")

        if self.capture_torch_profiler and self.profiler != "torch":
            raise ValueError(
                "capture_torch_profiler is only applicable when profiler is "
                "set to 'torch'"

View on GitHub (pinned to c794754062)

Solutions

Point proton_profiler_dir at a local directory (e.g. /tmp/proton).
Upload the local output to the bucket after profiling completes (separate step).

Example fix

# before
ProfilerConfig(profiler='proton', proton_profiler_dir='gs://bucket/prof')

# after
ProfilerConfig(profiler='proton', proton_profiler_dir='/tmp/prof')  # sync to bucket afterwards

Defensive patterns

Strategy: validation

Validate before calling

def is_uri(path: str) -> bool:
    return "://" in path and len(path.split("://")[0]) > 1

def validate_proton_dir(proton_dir: str) -> None:
    if is_uri(proton_dir):
        raise SystemExit("proton_profiler_dir must be local; sync to remote storage afterwards")

Type guard

def is_local_proton_dir(path: str) -> bool:
    return "://" not in path

Prevention

Do not reuse remote trace-bucket URIs that work for torch_profiler_dir with proton; proton requires local writes.

When it happens

Trigger: Setting proton_profiler_dir='gs://my-bucket/profiles' or any s3:// / hdfs:// style path while profiler='proton'.

Common situations: Cloud deployments reusing a remote trace bucket path that worked for torch_profiler_dir (which does support URIs); CI configs with uniform remote artifact paths.

Related errors

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