sgl-project/sglang · error · ValueError

--load-publish-endpoint needs an active --kv-events-config p

Error message

--load-publish-endpoint needs an active --kv-events-config publisher; got publisher='null' or an empty endpoint.

What it means

Raised during ServerArgs validation when --load-publish-endpoint is set but the --kv-events-config does not describe an active publisher. SGLang requires a functioning KV events publisher (non-'null' publisher with a non-empty endpoint) before load-publish (KV transfer publication) can be enabled.

Source

Thrown at python/sglang/srt/server_args.py:10519

        server_cfg = resolving_view(self)

        from sglang.srt.disaggregation.kv_events import (
            KVEventsConfig,
            resolve_load_pub_range,
        )

        if not self.kv_events_config:
            raise ValueError(
                "--load-publish-endpoint requires --kv-events-config: routers"
                " discover the load range through /server_info's kv_events"
                " block, absent without a publisher."
            )
        try:
            cfg = KVEventsConfig.from_cli(self.kv_events_config)
        except Exception as e:
            raise ValueError(f"--kv-events-config is not parseable: {e}")
        if cfg.publisher == "null" or not cfg.endpoint:
            raise ValueError(
                "--load-publish-endpoint needs an active --kv-events-config"
                " publisher; got publisher='null' or an empty endpoint."
            )
        _, reason = resolve_load_pub_range(
            kv_endpoint=cfg.endpoint,
            replay_endpoint=cfg.replay_endpoint,
            dp_size=server_cfg.dp_size,
            load_publish_endpoint=mode,
        )
        if reason:
            raise ValueError(reason)

    def check_lora_server_args(self):
        cfg = resolving_view(self)

        assert cfg.max_loras_per_batch > 0, "max_loras_per_batch must be positive"

        # Enable LoRA if any LoRA paths are provided for backward compatibility.

View on GitHub (pinned to 0132848349)

Solutions

1. Set --kv-events-config with an active publisher, e.g. publisher='redis' and a valid endpoint, then keep --load-publish-endpoint enabled
2. Verify KVEventsConfig.from_cli parses your config and that cfg.publisher != 'null' and cfg.endpoint is non-empty before starting the server
3. Drop --load-publish-endpoint if you do not need KV load publication

Example fix

# before
--kv-events-config '{"publisher": "null", "endpoint": ""}' --load-publish-endpoint ...
# after
--kv-events-config '{"publisher": "redis", "endpoint": "redis://localhost:6379"}' --load-publish-endpoint ...

from sglang.srt.server_args import KVEventsConfig
cfg = KVEventsConfig.from_cli(kv_events_config_str)
assert cfg.publisher != 'null' and cfg.endpoint, 'need an active publisher before --load-publish-endpoint'

When it happens

Trigger: Passing --load-publish-endpoint with a --kv-events-config that is omitted, uses publisher='null', or specifies an empty endpoint string.

Common situations: Enabling the KV-cache transfer/load-publish feature without first wiring up a KV events broker (Redis/Kafka/NATS); typos or copy-paste of a kv-events config that only sets the endpoint but leaves publisher as the default 'null'.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• DeepSeekV4 only supports interleave CP strategy, got {cfg.cp
• HiSparse requires one of {HISPARSE_KV_CACHE_DTYPES} KV cache
• MiniCPM does not support DP attention
• TensorRT-LLM MLA backend only supports kv-cache-dtype of fp8
• tokenspeed_mla backend requires kv-cache-dtype=fp8_e4m3, got

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