vllm-project/vllm · error · ValueError

{output_format} output requires proton_data='tree'

Error message

{output_format} output requires proton_data='tree'

What it means

ProfilerConfig raises when proton_output_format is 'hatchet' or 'hatchet_msgpack' but proton_data is not 'tree'. Hatchet formats are produced from the hierarchical tree profile data; trace-mode data cannot be serialized to hatchet.

Source

Thrown at vllm/config/profiler.py:229

            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'"
            )

        return self

View on GitHub (pinned to c794754062)

Solutions

1. Set proton_data='tree' (the default) when using hatchet/hatchet_msgpack output.
2. Or keep proton_data='trace' and use proton_output_format='chrome_trace'.

Example fix

# before
ProfilerConfig(profiler='proton', proton_profiler_dir='/tmp/p', proton_data='trace', proton_output_format='hatchet')

# after
ProfilerConfig(profiler='proton', proton_profiler_dir='/tmp/p', proton_output_format='hatchet')  # proton_data defaults to 'tree'

def validate_proton_output(data: str, fmt: str | None) -> None:
    if fmt in ("hatchet", "hatchet_msgpack") and data != "tree":
        raise SystemExit(f"proton_output_format={fmt!r} requires proton_data='tree'")

When it happens

Trigger: Passing proton_output_format='hatchet' (or 'hatchet_msgpack') with proton_data='trace' while profiler='proton'.

Common situations: Configs that set proton_data='trace' for Chrome traces then switch only the output format to hatchet without reverting the data mode.

Related errors

• {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
• chrome_trace output requires proton_data='trace'
• Unable to use nsight profiling unless workers run with Ray.

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