sgl-project/sglang · error · ValueError

SGLANG_RUST_SERVER serves the PD KV bootstrap registry on th

Error message

SGLANG_RUST_SERVER serves the PD KV bootstrap registry on the api port itself; --disaggregation-bootstrap-port {} conflicts with --port {}. Drop --disaggregation-bootstrap-port (decode nodes and the PD router must then target the prefill api port).

What it means

When SGLANG_RUST_SERVER is enabled, the PD KV bootstrap registry is served on the main API port, so an explicitly set --disaggregation-bootstrap-port that differs from both the default and --port is rejected to avoid ambiguity about where decode nodes should connect.

Source

Thrown at python/sglang/srt/arg_groups/pd_disaggregation_hook.py:166

def _alias_bootstrap_port_to_api_port(server_args: ServerArgs) -> None:
    """Rust-server prefill serves the KV bootstrap registry on the api listener
    itself, so the resolved bootstrap port must BE the api port — every internal
    consumer (KVManager registration, PrefillBootstrapQueue) reads the resolved
    field and agrees automatically. Decode is untouched: there the field names
    the PREFILL side's bootstrap port and must stay as the operator set it.
    """
    cfg = resolving_view(server_args)
    default_port = next(
        f.default
        for f in dataclasses.fields(server_args)
        if f.name == "disaggregation_bootstrap_port"
    )
    if cfg.disaggregation_bootstrap_port not in (
        default_port,
        cfg.port,
    ):
        raise ValueError(
            "SGLANG_RUST_SERVER serves the PD KV bootstrap registry on the api "
            "port itself; --disaggregation-bootstrap-port "
            f"{cfg.disaggregation_bootstrap_port} conflicts with --port "
            f"{cfg.port}. Drop --disaggregation-bootstrap-port (decode "
            "nodes and the PD router must then target the prefill api port)."
        )
    if cfg.disaggregation_bootstrap_port != cfg.port:
        logger.info(
            "SGLANG_RUST_SERVER: KV bootstrap registry is served on the api "
            "port; disaggregation_bootstrap_port %d -> %d",
            cfg.disaggregation_bootstrap_port,
            cfg.port,
        )
        declare_resolution(
            server_args,
            "_alias_bootstrap_port_to_api_port",
            disaggregation_bootstrap_port=cfg.port,
        )

View on GitHub (pinned to 0132848349)

Solutions

1. Drop --disaggregation-bootstrap-port entirely (decode nodes/router then target the prefill API port)
2. Or set it equal to --port
3. Or unset SGLANG_RUST_SERVER if you need a separate bootstrap port

Example fix

# before
SGLANG_RUST_SERVER=1 --disaggregation-bootstrap-port 8999 --port 8000
# after
SGLANG_RUST_SERVER=1 --port 8000

if os.environ.get("SGLANG_RUST_SERVER"):
    cfg.disaggregation_bootstrap_port = None  # let it default to api port

When it happens

Trigger: SGLANG_RUST_SERVER enabled plus --disaggregation-bootstrap-port set to a value that is neither the field default nor equal to --port.

Common situations: Porting a classic (non-rust-server) disaggregated config that pins a dedicated bootstrap port onto the rust-server runtime.

Related errors

• MiniCPM sparse attention does not support PD disaggregation
• PD decode DCP requires --disaggregation-transfer-backend moo
• PD decode DCP currently requires chunk cache; --disaggregati
• PD decode DCP currently requires chunk cache; --enable-hiera
• --disaggregation-decode-enable-radix-cache is incompatible w

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