sgl-project/sglang · error · ValueError

When enabling two batch overlap without an EP a2a backend (m

Error message

When enabling two batch overlap without an EP a2a backend (moe_a2a_backend='none'), --enable-dp-attention is required (DeepSeek-V4 non-EP DP TBO path).

What it means

Raised in check_server_args when two-batch overlap (TBO) is enabled with moe_a2a_backend='none' (no EP all-to-all) and --enable-dp-attention is off and this is not the CP-TBO path. For the non-EP DeepSeek-V4 DP TBO path, DP attention is a prerequisite, so the combination is rejected.

Source

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

    def _check_two_batch_overlap(self):
        # With no EP a2a backend, two-batch-overlap is only valid on the non-EP
        # DP TP-MoE path (overlapping the DP all_gatherv / reduce_scatterv with
        # the other ubatch's compute), which requires DP attention. Enabling it
        # there needs no extra opt-in env flag.
        cfg = resolving_view(self)

        cp_tbo = (
            is_hip()
            and cfg.enable_dsa_prefill_context_parallel
            and cfg.dsa_prefill_cp_mode == "round-robin-split"
        )
        if (
            cfg.enable_two_batch_overlap
            and cfg.moe_a2a_backend == "none"
            and not cfg.enable_dp_attention
            and not cp_tbo
        ):
            raise ValueError(
                "When enabling two batch overlap without an EP a2a backend "
                "(moe_a2a_backend='none'), --enable-dp-attention is required "
                "(DeepSeek-V4 non-EP DP TBO path)."
            )

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

        # Check parallel size constraints
        if cfg.ep_join_mode != "scale":
            assert (
                cfg.tp_size * cfg.pp_size
            ) % cfg.nnodes == 0, "tp_size must be divisible by number of nodes"

        assert (
            cfg.pp_max_micro_batch_size is None or cfg.pp_max_micro_batch_size >= 1
        ), (
            "pp_max_micro_batch_size must be a positive integer or None (for auto-compute). "

View on GitHub (pinned to 0132848349)

Solutions

Add --enable-dp-attention alongside TBO for the non-EP path
Or configure an EP a2a backend (e.g. --moe-a2a-backend deepep) instead
Or disable TBO if neither DP attention nor EP applies to your deployment

Example fix

# before
--enable-two-batch-overlap
# after
--enable-two-batch-overlap --enable-dp-attention

Defensive patterns

Strategy: validation

Validate before calling

if args.enable_two_batch_overlap and args.moe_a2a_backend == 'none':
    assert args.enable_dp_attention or args.context_parallel_size and args.context_parallel_size > 1, \
        'non-EP TBO requires --enable-dp-attention'

Try / catch

except ValueError as e:
    if 'two batch overlap' in str(e):
        args.enable_dp_attention = True  # retry with DP attention on

Prevention

Treat TBO flags as a bundle: TBO needs DP attention or an EP a2a backend
Don't copy EP-cluster flags verbatim into non-EP deployments

When it happens

Trigger: Launching with --enable-two-batch-overlay without --enable-dp-attention and without an EP a2a backend (default moe_a2a_backend='none'), outside the context-parallel TBO path.

Common situations: Enabling TBO for throughput on a single TP group without DP attention; copying TBO flags from an EP deployment to a non-EP one; upgrading where this constraint was introduced.

Related errors

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