vllm-project/vllm · error · ValueError

collect_detailed_traces requires `--otlp-traces-endpoint` to

Error message

collect_detailed_traces requires `--otlp-traces-endpoint` to be set.

What it means

A model validator on ObservabilityConfig requires otlp_traces_endpoint to be set whenever collect_detailed_traces is non-empty. Detailed tracing (per-module latency instrumentation) is exported through OTLP, so requesting it without an endpoint has nowhere to send data and is rejected.

Source

Thrown at vllm/config/observability.py:156

                    f"installed. Original error:\n{otel_import_error_traceback}"
                )
        return value

    @field_validator("collect_detailed_traces")
    @classmethod
    def _validate_collect_detailed_traces(
        cls, value: list[DetailedTraceModules] | None
    ) -> list[DetailedTraceModules] | None:
        """Handle the legacy case where users might provide a comma-separated
        string instead of a list of strings."""
        if value is not None and len(value) == 1 and "," in value[0]:
            value = cast(list[DetailedTraceModules], value[0].split(","))
        return value

    @model_validator(mode="after")
    def _validate_tracing_config(self):
        if self.collect_detailed_traces and not self.otlp_traces_endpoint:
            raise ValueError(
                "collect_detailed_traces requires `--otlp-traces-endpoint` to be set."
            )
        return self

View on GitHub (pinned to c794754062)

Solutions

1. Set an OTLP endpoint: --otlp-traces-endpoint http://localhost:4317 (or your collector's URL).
2. If you do not have a collector, remove --collect-detailed-traces entirely.
3. Ensure the OTel packages are installed too, or error 268 fires next.

Example fix

# before
vllm serve model --collect-detailed-traces model

# after
vllm serve model --otlp-traces-endpoint http://localhost:4317 --collect-detailed-traces model

def check_tracing_pair(collect: list[str] | None, endpoint: str | None) -> None:
    if collect and not endpoint:
        raise SystemExit("--collect-detailed-traces requires --otlp-traces-endpoint")

When it happens

Trigger: Passing --collect-detailed-traces model,worker,framework (or the legacy comma-string form) without --otlp-traces-endpoint; programmatically ObservabilityConfig(collect_detailed_traces=["model"]) with no endpoint.

Common situations: Copy-pasting a tracing section from docs but trimming 'unneeded' OTLP flags; enabling detailed traces for local debugging without standing up a collector.

Related errors

• 'mm_shm_cache_max_object_size_mb' should only be set when 'm
• 'mm_encoder_fp8_scale_path' and 'mm_encoder_fp8_scale_save_p
• 'mm_encoder_fp8_scale_save_path' cannot be used with 'mm_enc
• Invalid "device" in mm_processor_kwargs: {device!r}. Expecte
• OpenTelemetry is not available. Unable to configure 'otlp_tr

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