{"record":{"id":"1786e70bd933eeee","repo":"sgl-project/sglang","slug":"memory-position-mode-must-be-one-of-reference","errorCode":null,"errorMessage":"memory_position_mode must be one of {'reference', 'legacy', 'prefix_continuous'}, got {mode}","messagePattern":"memory_position_mode must be one of (.+?), got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/joy_echo/memory.py","lineNumber":399,"sourceCode":"            per_slot_latents.append(packed)\n        packed_latents.append(torch.cat(per_slot_latents, dim=1))\n\n    return torch.cat(packed_latents, dim=0)\n\n\n# --- Memory RoPE coordinates ---\n\n\n# Official ltx_wrapper hardcodes VIDEO_FPS=24.0 for RoPE position conversion.\nJOYAI_VIDEO_ROPE_FPS = 24.0\n\n\ndef normalize_memory_position_mode(mode: str) -> str:\n    normalized = str(mode).lower()\n    if normalized == \"reference\":\n        return \"legacy\"\n    if normalized not in {\"legacy\", \"prefix_continuous\"}:\n        raise ValueError(\n            \"memory_position_mode must be one of \"\n            \"{'reference', 'legacy', 'prefix_continuous'}, \"\n            f\"got {mode}\"\n        )\n    return normalized\n\n\ndef apply_memory_video_downscale(\n    video_coords: torch.Tensor,\n    downscale_factor: int,\n) -> torch.Tensor:\n    if int(downscale_factor) == 1:\n        return video_coords\n    scaled = video_coords.clone()\n    scaled[:, 1, ...] *= int(downscale_factor)\n    scaled[:, 2, ...] *= int(downscale_factor)\n    return scaled\n","sourceCodeStart":381,"sourceCodeEnd":417,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/joy_echo/memory.py#L381-L417","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Set memory_position_mode to one of the literal strings 'reference', 'legacy', or 'prefix_continuous' (all lowercase, underscores)","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","Check for renamed options after upgrading sglang/multimodal_gen — an old value like 'contiguous' should map to 'prefix_continuous'"],"exampleFix":"# before\ncoords = build_memory_video_rope_coords(..., memory_position_mode=\"prefix-continuous\")\n# after\ncoords = build_memory_video_rope_coords(..., memory_position_mode=\"prefix_continuous\")","handlingStrategy":"validation","validationCode":"ALLOWED = {\"reference\", \"legacy\", \"prefix_continuous\"}\nif str(mode).lower() not in ALLOWED:\n    raise ValueError(f\"memory_position_mode must be one of {sorted(ALLOWED)}, got {mode!r}\")","typeGuard":"def is_valid_memory_position_mode(mode: str) -> bool:\n    return isinstance(mode, str) and mode.lower() in {\"reference\", \"legacy\", \"prefix_continuous\"}","tryCatchPattern":"try:\n    coords = build_memory_video_rope_coords(..., memory_position_mode=mode)\nexcept ValueError as e:\n    if \"memory_position_mode\" in str(e):\n        mode = \"legacy\"  # safe default\n        coords = build_memory_video_rope_coords(..., memory_position_mode=mode)\n    else:\n        raise","preventionTips":["Use argparse choices=['reference','legacy','prefix_continuous'] for CLI-exposed config","Centralize config parsing so user strings are validated once at load time"],"tags":["joy-echo","memory","rope","config-validation","multimodal"],"backgroundTag":"invalid-enum-value","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}