sgl-project/sglang · error · HTTPException

Invalid X-Data-Parallel-Rank header: must be an integer, got

Error message

Invalid X-Data-Parallel-Rank header: must be an integer, got '{header_value}'

What it means

OpenAIServingBase.extract_routed_dp_rank_from_header raises HTTP 400 when the X-Data-Parallel-Rank request header is present but not parseable as an integer. The header is used to pin requests to a specific data-parallel rank and overrides the body's routed_dp_rank.

Source

Thrown at python/sglang/srt/entrypoints/openai/serving_base.py:288

        """
        if raw_request is None:
            return body_routed_dp_rank

        header_value = raw_request.headers.get("x-data-parallel-rank")
        if header_value is not None:
            try:
                header_dp_rank = int(header_value)
                if (
                    body_routed_dp_rank is not None
                    and header_dp_rank != body_routed_dp_rank
                ):
                    logger.debug(
                        f"X-Data-Parallel-Rank header ({header_dp_rank}) overrides "
                        f"body routed_dp_rank ({body_routed_dp_rank})"
                    )
                return header_dp_rank
            except ValueError:
                raise HTTPException(
                    status_code=400,
                    detail=f"Invalid X-Data-Parallel-Rank header: must be an integer, got '{header_value}'",
                )

        return body_routed_dp_rank

View on GitHub (pinned to 0132848349)

Solutions

1. Send an integer string, e.g. X-Data-Parallel-Rank: 3
2. Omit the header and set routed_dp_rank in the JSON body instead
3. Strip the header at the proxy if you don't intend per-rank routing

Example fix

# before
X-Data-Parallel-Rank: rank-1
# after
X-Data-Parallel-Rank: 1

v = headers.get("X-Data-Parallel-Rank")
if v is not None:
    int(v)  # raises if invalid; fix or drop before sending

def valid_dp_rank_header(v): 
    try: int(v); return True
    except (TypeError, ValueError): return False

except HTTPError as e:
    if e.response.status_code == 400 and 'X-Data-Parallel-Rank' in e.response.text: headers.pop('X-Data-Parallel-Rank'); retry()

When it happens

Trigger: Any /v1/... request with header X-Data-Parallel-Rank: "abc" or "1.5" (non-integer string), while the router feature is enabled.

Common situations: Load balancers or proxies appending stringified floats; clients passing rank names like 'rank-0'; misconfigured HTTP clients sending the header with whitespace/quotes.

Related errors

• routed_dp_rank={routed_dp_rank} out of range [0, {dp_size})
• 'data_parallel_rank' is deprecated, use 'routed_dp_rank' ins
• Unknown serve backend {name!r}. Available values: {available
• Multiple distributions register serve backend {name!r}: {pro
• Failed to load serve backend {name!r} from {self._entry_poin

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/b9001052b16899ec. Report an issue: GitHub.