sgl-project/sglang · error · ValueError

memory_position_mode must be one of {'reference', 'legacy',

Error message

memory_position_mode must be one of {'reference', 'legacy', 'prefix_continuous'}, got {mode}

What it means

The memory position mode argument for Joy-Echo memory RoPE construction must be one of 'reference', 'legacy', or 'prefix_continuous'. 'reference' is normalized to 'legacy'; any other string (after lowercasing) is rejected because the RoPE coordinate builder has no code path for it. This guards the position-encoding layout of the memory prefix before coordinates are generated.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/joy_echo/memory.py:399

            per_slot_latents.append(packed)
        packed_latents.append(torch.cat(per_slot_latents, dim=1))

    return torch.cat(packed_latents, dim=0)


# --- Memory RoPE coordinates ---


# Official ltx_wrapper hardcodes VIDEO_FPS=24.0 for RoPE position conversion.
JOYAI_VIDEO_ROPE_FPS = 24.0


def normalize_memory_position_mode(mode: str) -> str:
    normalized = str(mode).lower()
    if normalized == "reference":
        return "legacy"
    if normalized not in {"legacy", "prefix_continuous"}:
        raise ValueError(
            "memory_position_mode must be one of "
            "{'reference', 'legacy', 'prefix_continuous'}, "
            f"got {mode}"
        )
    return normalized


def apply_memory_video_downscale(
    video_coords: torch.Tensor,
    downscale_factor: int,
) -> torch.Tensor:
    if int(downscale_factor) == 1:
        return video_coords
    scaled = video_coords.clone()
    scaled[:, 1, ...] *= int(downscale_factor)
    scaled[:, 2, ...] *= int(downscale_factor)
    return scaled

View on GitHub (pinned to 0132848349)

Solutions

1. Set memory_position_mode to one of the literal strings 'reference', 'legacy', or 'prefix_continuous' (all lowercase, underscores)
2. If the value comes from user config, call normalize_memory_position_mode early and surface the allowed set in your own error message or argparse choices
3. Check for renamed options after upgrading sglang/multimodal_gen — an old value like 'contiguous' should map to 'prefix_continuous'

Example fix

# before
coords = build_memory_video_rope_coords(..., memory_position_mode="prefix-continuous")
# after
coords = build_memory_video_rope_coords(..., memory_position_mode="prefix_continuous")

ALLOWED = {"reference", "legacy", "prefix_continuous"}
if str(mode).lower() not in ALLOWED:
    raise ValueError(f"memory_position_mode must be one of {sorted(ALLOWED)}, got {mode!r}")

def is_valid_memory_position_mode(mode: str) -> bool:
    return isinstance(mode, str) and mode.lower() in {"reference", "legacy", "prefix_continuous"}

try:
    coords = build_memory_video_rope_coords(..., memory_position_mode=mode)
except ValueError as e:
    if "memory_position_mode" in str(e):
        mode = "legacy"  # safe default
        coords = build_memory_video_rope_coords(..., memory_position_mode=mode)
    else:
        raise

When it happens

Trigger: Calling build_memory_video_rope_coords or build_memory_audio_rope_coords (or the model stage's _build_memory_model_inputs) with memory_position_mode set to a misspelled or unsupported value, e.g. 'prefix-continuous', 'contiguous', 'PrefixContinuous' (case is fine, it lowercases, but hyphenation/typos are not).

Common situations: Copying a config key from a different codebase or doc that uses different naming; renaming config options across versions of the multimodal_gen pipeline; passing a user-supplied CLI/config string straight through without validation.

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

• Invalid latent grid for memory RoPE: {latent_height=} {laten
• memory_video_len must be a multiple of latent_height * laten
• cos/sin shape does not cover image tokens and head_dim
• Invalid fused KV rotary/head dim pair: rotary_dim={rotary_di
• Invalid fused KV rotary/head dim pair: rotary_dim={self.rota

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