sgl-project/sglang · error · ValueError

{path}.kind must be a non-empty string

Error message

{path}.kind must be a non-empty string

What it means

The ref2va packed-sequence builder validates each entry of ref_blocks and requires a non-empty string under the 'kind' (or legacy 'type') key. This ValueError fires when an entry is a Mapping but its kind field is missing, None, or an empty/non-string value. It exists to fail fast before any layout math, since downstream code dispatches on kind ('image', 'audio', 'video').

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/packed_sequence.py:321

    Comfy's hybrid Ref2VA + guide layout. Video-bearing blocks pack their audio
    rows immediately before their video rows; both share the same temporal
    origin and advance by the longer of the audio and video spans. Standalone
    audio advances the target origin by its own T, and image blocks advance it
    by one integer slot.
    """
    if not isinstance(ref_blocks, Sequence) or isinstance(ref_blocks, (str, bytes)):
        raise ValueError("ref_blocks must be a sequence")

    parsed: list[dict[str, object]] = []
    ref_visual_rows = 0
    ref_audio_rows = 0
    for index, raw in enumerate(ref_blocks):
        path = f"ref_blocks[{index}]"
        if not isinstance(raw, Mapping):
            raise ValueError(f"{path} must be an object")
        kind = raw.get("kind", raw.get("type"))
        if not isinstance(kind, str) or not kind:
            raise ValueError(f"{path}.kind must be a non-empty string")
        if kind == "image":
            rh = _positive_int(raw, "latent_h", path)
            rw = _positive_int(raw, "latent_w", path)
            rows = (rh // _PATCH_H) * (rw // _PATCH_W)
            item = {"kind": kind, "latent_h": rh, "latent_w": rw, "rows": rows}
            ref_visual_rows += rows
        elif kind == "audio":
            rt = _positive_int(raw, "ref_audio_t", path, allow_zero=True)
            rows = rt * audio_channel
            item = {"kind": kind, "ref_audio_t": rt, "audio_rows": rows}
            ref_audio_rows += rows
        elif kind in ("video", "video_audio"):
            rt = _positive_int(raw, "ref_audio_t", path, allow_zero=True)
            vt = _positive_int(raw, "latent_t", path)
            vh = _positive_int(raw, "latent_h", path)
            vw = _positive_int(raw, "latent_w", path)
            frame_rows = (vh // _PATCH_H) * (vw // _PATCH_W)
            audio_rows = rt * audio_channel

View on GitHub (pinned to 0132848349)

Solutions

1. Set a non-empty 'kind' string on every ref_blocks entry (accepted values: image, audio, video).
2. If your payload uses 'type', that alias is accepted — otherwise rename your key to 'kind'.
3. Add a preflight pass that rejects ref_blocks entries without a valid kind before calling the packer.

Example fix

# before
ref_blocks = [{"media_type": "image", "latent_h": 32, "latent_w": 32}]

# after
ref_blocks = [{"kind": "image", "latent_h": 32, "latent_w": 32}]

def validate_ref_blocks(ref_blocks):
    for i, raw in enumerate(ref_blocks):
        kind = raw.get("kind", raw.get("type")) if isinstance(raw, Mapping) else None
        if not isinstance(kind, str) or not kind:
            raise ValueError(f"ref_blocks[{i}] missing non-empty 'kind'")

from collections.abc import Mapping

def is_valid_ref_block(raw) -> bool:
    return (
        isinstance(raw, Mapping)
        and isinstance(raw.get("kind", raw.get("type")), str)
        and bool(raw.get("kind", raw.get("type")))
    )

When it happens

Trigger: Calling minimax_h3_packed_sequence_ref2va_blocks (directly or via _build_packed_layout/_branch) with ref_blocks containing an entry like {}, {'kind': None}, {'kind': ''}, {'kind': 3}, or an entry that only uses a key other than 'kind'/'type'.

Common situations: Building ref_blocks from loosely-typed user JSON or an LLM-generated media spec; renaming the discriminator key in a schema migration; an entry that uses 'media_type' or 'modality' instead of 'kind'/'type'.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• {path}.kind unsupported for ref2va: {kind!r}
• Feature attrs ({_mm_feature_attrs[modality]}) not found in {
• Z-Image text embeddings must have shape [seq, dim] or [batch
• f"Unsupported patch_size type: {type(patch_size)}"
• f"Expected camera embedding shape [B, C, F, H, W], got {tupl

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