sgl-project/sglang · error · ValueError

Invalid attention metadata values.Sparsity should be in [0,

Error message

Invalid attention metadata values.Sparsity should be in [0, 1), skip_first_steps should be non-negative.Got sparsity={sparsity}, skip_first_steps={skip_first_steps}

What it means

BlockSparseAttentionMetadata.build validates its sparsity arguments: sparsity must be in [0.0, 1.0) and skip_first_steps >= 0. Violations mean the block-sparse mask would be nonsensical, so it fails fast at metadata construction time.

Source

Thrown at python/sglang/multimodal_gen/runtime/layers/attention/backends/block_sparse_attn.py:93

        Args:
            current_timestep: The current diffusion timestep.
            skip_first_steps: Number of initial timesteps to skip before applying
                sparsity. Must be non‑negative.
            sparsity: Fraction of tokens to drop (block‑wise) in the block sparse
                attention mechanism. Must be in the range [0.0, 1.0).
            raw_latent_shape: Shape of the latent tensor before patching.
            patch_size: Patch size as (T, height, width). Only the height
                and width components are used to divide the latent dimensions.
            **kwargs: Additional keyword arguments (ignored, but accepted for
                compatibility with base class or calling conventions).

        Returns:
            BlockSparseAttentionMetadata
        Note:
            The `block_frame_stride` is needed to set the first blocks to be non‑sparse.
        """
        if not (skip_first_steps >= 0 and 0.0 <= sparsity < 1.0):
            raise ValueError(
                (
                    "Invalid attention metadata values."
                    f"Sparsity should be in [0, 1), skip_first_steps should be non-negative."
                    f"Got sparsity={sparsity}, skip_first_steps={skip_first_steps}"
                )
            )

        if sparsity == 0.0:
            logger.warning(
                (
                    "Sparsity is set to 0.0, which means no tokens will be dropped."
                    "For better performance use Laser Attention or increase sparsity."
                )
            )

        if len(raw_latent_shape) >= 5:
            latent_height, latent_width = raw_latent_shape[3:5]
        else:

View on GitHub (pinned to 0132848349)

Solutions

1. Fix the values so 0.0 <= sparsity < 1.0 and skip_first_steps >= 0
2. If your config holds density, convert with sparsity = 1 - density
3. Clamp/validate the two values where the config is parsed, before build() is called

Example fix

# before
meta = BlockSparseAttentionMetadata.build(sparsity=0.75 /* actually density */, skip_first_steps=-1, ...)
# after
sparsity = 1.0 - density
assert 0.0 <= sparsity < 1.0 and skip_first_steps >= 0
meta = BlockSparseAttentionMetadata.build(sparsity=sparsity, skip_first_steps=max(0, skip_first_steps), ...)

assert 0.0 <= sparsity < 1.0, f"sparsity {sparsity} out of [0,1)"
assert skip_first_steps >= 0, "skip_first_steps must be non-negative"

try:
    meta = BlockSparseAttentionMetadata.build(sparsity=s, skip_first_steps=n, ...)
except ValueError as e:
    if "Invalid attention metadata values" in str(e):
        s, n = sanitize_sparsity_args(s, n)
        meta = BlockSparseAttentionMetadata.build(sparsity=s, skip_first_steps=n, ...)

When it happens

Trigger: Calling BlockSparseAttentionMetadata.build with sparsity >= 1.0, negative sparsity, or negative skip_first_steps.

Common situations: Config files that specify density (fraction kept) where the API expects sparsity; typos like sparsity: -0.1 or 1.2; negative skip_first_steps intended to mean 'attend from step 0'.

Related errors

• {name}_block_cnt and {name}_block_idx must both be provided
• Invalid attention metadata values.Sparsity should be in [0,
• {tensor_name}{context_clause} with shape {tensor.shape} cann
• {name}_block tensors must have dtype torch.int32
• {name}_block_cnt and {name}_block_idx must be on the same de

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