sgl-project/sglang · error · ValueError

HiSparse supports DSA {label} backend(s) {sorted(allowed_bac

Error message

HiSparse supports DSA {label} backend(s) {sorted(allowed_backends)} on this platform with --kv-cache-dtype={kv_cache_dtype}, but got --dsa-{label}-backend={backend}. Please use one of {sorted(allowed_backends)}, or omit the option to let SGLang pick a backend for this platform.

What it means

For HiSparse DSA (DeepSeek sparse attention) prefill/decode backends, the set of allowed backends depends on the platform and the --kv-cache-dtype value. If you explicitly pass --dsa-prefill-backend or --dsa-decode-backend with a value not in the allowed set, SGLang raises this error instead of silently falling back.

Source

Thrown at python/sglang/srt/arg_groups/hisparse_hook.py:57

# The hisparse DSA backend defaults moved to the resolution pipeline
# (arg_groups/overrides.py: _dsa_split_backend_resolution, hisparse arm).


def validate_hisparse_dsa_backend(
    server_args: ServerArgs, attr: str, label: str
) -> None:
    from sglang.srt.arg_groups.overrides import resolved_view

    # Invoked after the DSA kv-cache-dtype / split-backend declarations:
    # read the resolving state through the view.
    view = resolved_view(server_args)
    backend = getattr(view, attr)
    kv_cache_dtype = view.kv_cache_dtype
    allowed_backends = _hisparse_allowed_backends(kv_cache_dtype)
    if backend is not None and backend not in allowed_backends:
        raise ValueError(
            f"HiSparse supports DSA {label} backend(s) {sorted(allowed_backends)} "
            f"on this platform with --kv-cache-dtype={kv_cache_dtype}, "
            f"but got --dsa-{label}-backend={backend}. "
            f"Please use one of {sorted(allowed_backends)}, or omit the option "
            "to let SGLang pick a backend for this platform."
        )


def validate_hisparse_kv_cache_dtype(server_args: ServerArgs) -> None:
    from sglang.srt.arg_groups.overrides import resolved_view

    kv_cache_dtype = resolved_view(server_args).kv_cache_dtype
    if kv_cache_dtype in HISPARSE_KV_CACHE_DTYPES:
        return

    choices = " or ".join(
        f"--kv-cache-dtype={dtype}" for dtype in HISPARSE_KV_CACHE_DTYPES
    )

View on GitHub (pinned to 0132848349)

Solutions

1. Omit --dsa-prefill-backend/--dsa-decode-backend and let SGLang auto-pick for the platform
2. Set the backend to one of the values listed in sorted(allowed_backends) in the message
3. Change --kv-cache-dtype so the desired backend becomes allowed

Example fix

# before
--kv-cache-dtype fp8_e4m3 --dsa-decode-backend tilelang
# after
--kv-cache-dtype fp8_e4m3 --dsa-decode-backend flashmla_kv

from sglang.srt.arg_groups.hisparse_hook import _hisparse_allowed_backends
allowed = _hisparse_allowed_backends(view.kv_cache_dtype)
if backend is not None and backend not in allowed:
    backend = None  # let SGLang auto-pick

except ValueError as e:
    if 'dsa-' in str(e) and 'backend' in str(e): drop_dsa_backend_flags(); retry()
    raise

When it happens

Trigger: Passing --dsa-prefill-backend=<b> or --dsa-decode-backend=<b> where <b> is not returned by _hisparse_allowed_backends(kv_cache_dtype) for the current platform, e.g. selecting a bf16-only kernel while kv_cache_dtype=fp8_e4m3.

Common situations: Copying dsa backend flags from a different GPU generation or dtype recipe; upgrading SGLang changed the allowed backend matrix; mixing fp8 KV cache with a kernel that only supports bf16.

Related errors

• HiSparse requires one of {HISPARSE_KV_CACHE_DTYPES} KV cache
• The hpc_ops attention backend with an fp8_e4m3 KV cache requ
• {selection_error}{component_suffix}
• No compatible attention backend is available{component_suffi
• Subclass {self.__class__.__name__} must define _supported_at

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