sgl-project/sglang · error · ValueError

miss_src, miss_dst, and miss_count must be provided together

Error message

miss_src, miss_dst, and miss_count must be provided together.

What it means

The speculative HiSparse loader's optional miss-plan recording takes a triple of tensors (miss_src, miss_dst, miss_count) that are written together by the kernel. Supplying miss_src without the other two (this branch triggers when miss_dst or miss_count is None while miss_src is set) would leave the plan half-initialized, so all three must be provided or none.

Source

Thrown at python/sglang/kernels/ops/kvcache/hisparse.py:105

) -> None:
    """Resolve all speculative steps and swap unique misses in one launch pair.

    Optional miss-plan outputs use the same protocol as the single-step HiSparse
    kernel, so shared-index layers can replay only the Host-to-GPU copies with
    ``copy_cache_planned_mla``.
    """
    _, num_steps, num_top_k = top_k_tokens.shape
    if not 2 <= num_steps <= 4:
        raise ValueError(
            f"HiSparse speculative swap requires 2-4 steps, got {num_steps}."
        )
    hot_buffer_size = state.cache_policy.size(1)
    page_size = device_buffer_tokens.size(1) - hot_buffer_size
    item_size_bytes = host_cache.stride(0) * host_cache.element_size()
    record_miss_plan = miss_src is not None
    if record_miss_plan:
        if miss_dst is None or miss_count is None:
            raise ValueError(
                "miss_src, miss_dst, and miss_count must be provided together."
            )
        if miss_src.dtype != torch.int64 or miss_dst.dtype != torch.int32:
            raise ValueError("miss_src must be int64 and miss_dst must be int32.")
        if miss_count.dtype != torch.int32:
            raise ValueError("miss_count must be int32.")
        plan_capacity = num_steps * num_top_k
        batch_size = top_k_tokens.size(0)
        if (
            miss_src.ndim != 2
            or miss_dst.ndim != 2
            or miss_src.size(0) < batch_size
            or miss_dst.size(0) < batch_size
            or miss_src.size(1) < plan_capacity
            or miss_dst.size(1) < plan_capacity
        ):
            raise ValueError(
                "speculative miss_src/miss_dst must have shape "

View on GitHub (pinned to 0132848349)

Solutions

1. Provide all three: miss_src (int64), miss_dst (int32), miss_count (int32)
2. Or pass none of them to disable miss-plan recording
3. Audit wrapper defaults so the three parameters default together

Example fix

# before
load_cache_to_device_buffer_spec_mla(..., miss_src=src)
# after
load_cache_to_device_buffer_spec_mla(..., miss_src=src, miss_dst=dst, miss_count=cnt)

provided = (miss_src is not None, miss_dst is not None, miss_count is not None)
assert all(provided) or not any(provided), 'miss-plan tensors are all-or-none'

def miss_plan_args_consistent(s, d, c) -> bool:
    p = (s is not None, d is not None, c is not None)
    return all(p) or not any(p)

When it happens

Trigger: Calling load_cache_to_device_buffer_spec_mla with miss_src set but miss_dst=None or miss_count=None.

Common situations: Wrapping the API and defaulting only some tensors to None; refactoring call sites that added miss-plan recording incrementally.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• attn_sink requires topk_length to be provided as well
• missing value for {a} (expected e.g. `{a} 2,4`)
• combined_history=True requires direction=0 (bidi)
• attn_res: nvb must be in [1, {_MAX_BANK_ROWS}], got {nvb}
• kv-canary: launch_canary_plan_kernels requires full_to_swa_i

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