sgl-project/sglang · error · ValueError

SGLANG_DIFFUSION_ATTENTION_CONFIG is not set

Error message

SGLANG_DIFFUSION_ATTENTION_CONFIG is not set

What it means

SlidingTileAttentionBackend.__init__ requires a mask strategy JSON whose path comes from get_global_server_args().attention_backend_config.mask_strategy_file_path (typically set via SGLANG_DIFFUSION_ATTENTION_CONFIG). If unset, it raises ValueError.

Source

Thrown at python/sglang/multimodal_gen/runtime/layers/attention/backends/sliding_tile_attn.py:127

    def __init__(
        self,
        num_heads: int,
        head_size: int,
        causal: bool,
        softmax_scale: float,
        num_kv_heads: int | None = None,
        prefix: str = "",
        **extra_impl_args,
    ) -> None:
        if not st_attn_backend_available:
            raise ValueError("st attn not supported")
        # TODO(will-refactor): for now this is the mask strategy, but maybe we should
        # have a more general config for STA?
        mask_strategy_file_path = (
            get_global_server_args().attention_backend_config.mask_strategy_file_path
        )
        if mask_strategy_file_path is None:
            raise ValueError("SGLANG_DIFFUSION_ATTENTION_CONFIG is not set")

        # TODO(kevin): get mask strategy for different STA modes
        with open(mask_strategy_file_path) as f:
            mask_strategy = json.load(f)
        self.mask_strategy = dict_to_3d_list(mask_strategy)

        self.prefix = prefix
        sp_group = get_sp_group()
        self.sp_size = sp_group.world_size
        # STA config
        self.STA_base_tile_size = [6, 8, 8]
        self.dit_seq_shape_mapping = RangeDict(
            {
                (115200, 115456): "30x48x80",
                82944: "36x48x48",
                69120: "18x48x80",
            }
        )

View on GitHub (pinned to 0132848349)

Solutions

1. Set the mask strategy config: export SGLANG_DIFFUSION_ATTENTION_CONFIG=/path/to/mask_strategy.json or pass attention_backend_config.mask_strategy_file_path
2. Verify the JSON file exists and parses (it is loaded with json.load in __init__)
3. If STA isn't intended, choose a different attention backend

Example fix

# before
python launch.py --attention-backend sliding_tile  # ValueError: SGLANG_DIFFUSION_ATTENTION_CONFIG is not set
# after
export SGLANG_DIFFUSION_ATTENTION_CONFIG=/models/sta/mask_strategy.json
python launch.py --attention-backend sliding_tile

import os
mask_path = get_global_server_args().attention_backend_config.mask_strategy_file_path
if not mask_path:
    raise SystemExit("set SGLANG_DIFFUSION_ATTENTION_CONFIG=<mask_strategy.json>")
assert os.path.isfile(mask_path), f"mask strategy file missing: {mask_path}"

try:
    backend = SlidingTileAttentionBackend(...)
except ValueError as e:
    if "SGLANG_DIFFUSION_ATTENTION_CONFIG" in str(e):
        os.environ['SGLANG_DIFFUSION_ATTENTION_CONFIG'] = DEFAULT_MASK_PATH
        backend = SlidingTileAttentionBackend(...)

When it happens

Trigger: Starting with the STA backend while attention_backend_config.mask_strategy_file_path is None (env var not exported / config not passed).

Common situations: Tutorials setting STA without the mask config env var; deploy scripts dropping the env var; the config key renamed across versions.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• st attn not supported
• TP size must be positive.
• Either spatial_upsample or temporal_upsample must be True
• Cosmos3 AVAE dec_strides product must equal hop_size: produc
• Unsupported DisaggregationMode: {disaggregation_mode}

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