sgl-project/sglang · error · ValueError

Invalid mode: {mode}, must be one of 'write', 'read', 'skip'

Error message

Invalid mode: {mode}, must be one of 'write', 'read', 'skip'

What it means

GlmImageLayerKVCache.set_mode validates the per-layer KV cache mode used in glm_image generation (write = populate cache during prefill/encoding, read = reuse cached keys/values, skip = bypass). Any mode string other than 'write', 'read', 'skip' (or None to clear) raises ValueError; it is called from forward.

Source

Thrown at python/sglang/multimodal_gen/runtime/models/dits/glm_image.py:218

    def clear(self):
        self.k_cache = None
        self.v_cache = None
        self.mode = None


class GlmImageKVCache:
    """Container for all layers' KV caches."""

    def __init__(self, num_layers: int):
        self.num_layers = num_layers
        self.caches = [GlmImageLayerKVCache() for _ in range(num_layers)]

    def __getitem__(self, layer_idx: int) -> GlmImageLayerKVCache:
        return self.caches[layer_idx]

    def set_mode(self, mode: Optional[str]):
        if mode is not None and mode not in ["write", "read", "skip"]:
            raise ValueError(
                f"Invalid mode: {mode}, must be one of 'write', 'read', 'skip'"
            )
        for cache in self.caches:
            cache.mode = mode

    def clear(self):
        for cache in self.caches:
            cache.clear()


class GlmImageTimestepEmbedding(nn.Module):
    """
    Replacement for diffusers TimestepEmbedding using ReplicatedLinear.
    Structure: linear_1 -> act(silu) -> linear_2
    """

    def __init__(
        self,

View on GitHub (pinned to 0132848349)

Solutions

1. Pass only 'write', 'read', 'skip', or None to set_mode; check casing
2. Update the caller in forward that derived the invalid mode string to emit one of the three canonical values
3. If adding a new mode, extend the allowed list in set_mode and the cache implementation together

Example fix

# before
caches.set_mode("WRITE")
# after
caches.set_mode("write")

if mode is not None:
    assert mode in {"write", "read", "skip"}, f"bad mode {mode!r}"

def is_valid_cache_mode(mode) -> bool:
    return mode is None or (isinstance(mode, str) and mode in {"write", "read", "skip"})

try:
    caches.set_mode(mode)
except ValueError:
    caches.set_mode("skip")  # safe fallback

When it happens

Trigger: forward() computes a mode string and passes it to set_mode; a mode like 'WRITE', 'cache', 'prefill', or an unexpected enum value triggers the error. Directly calling caches.set_mode('invalid') also triggers it.

Common situations: Refactoring the generation loop and renaming modes without updating set_mode call sites; passing an enum/str subclass whose value doesn't match; case mismatches ('Write' vs 'write').

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• v_cache must be provided
• k_cache can only be None when only_qv=True
• MXFP8 KV cache requires the FA4 backend.
• Out of memory. Try to lower your batch size.\nTry to allocat
• MXFP8 KV cache requires K and V scale tensors.

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