sgl-project/sglang · error · ValueError

Cosmos3 requires num_frames == action_horizon + 1, got num_f

Error message

Cosmos3 requires num_frames == action_horizon + 1, got num_frames={num_frames}, action_horizon={action_horizon}

What it means

When both action_horizon and num_frames are supplied to the Cosmos3 action endpoint, they must satisfy num_frames == action_horizon + 1 (the model generates one action per future frame beyond the conditioning frame). Passing an inconsistent pair is rejected before request construction.

Source

Thrown at python/sglang/multimodal_gen/runtime/entrypoints/action/cosmos3.py:156

            "Cosmos3 forward_dynamics produces video; use /v1/videos instead"
        )
    if action_mode not in ("policy", "inverse_dynamics"):
        raise ValueError(
            "Cosmos3 action endpoint supports action_mode='policy' or "
            "'inverse_dynamics'"
        )

    action_horizon = options.get("action_horizon")
    num_frames = options.get("num_frames")
    if action_horizon is None and num_frames is None:
        action_horizon = 16
    if action_horizon is not None:
        action_horizon = int(action_horizon)
        if action_horizon <= 0:
            raise ValueError("action_horizon must be a positive integer")
        expected_num_frames = action_horizon + 1
        if num_frames is not None and int(num_frames) != expected_num_frames:
            raise ValueError(
                "Cosmos3 requires num_frames == action_horizon + 1, got "
                f"num_frames={num_frames}, action_horizon={action_horizon}"
            )
        num_frames = expected_num_frames
    else:
        num_frames = int(num_frames)
        if num_frames <= 1:
            raise ValueError("Cosmos3 action num_frames must be greater than 1")
    if (num_frames - 1) % 4 != 0:
        raise ValueError(
            "Cosmos3 action_horizon must be divisible by 4 so num_frames "
            "is compatible with the temporal VAE"
        )

    images = _images_from_observation(observation)
    video_path = options.get("video_path") or observation.get("video")
    if action_mode == "policy" and not images:
        raise ValueError("Cosmos3 policy input requires an observation image")

View on GitHub (pinned to 0132848349)

Solutions

1. Set num_frames = action_horizon + 1, or omit num_frames entirely (it is derived from action_horizon)
2. If you must keep num_frames, derive action_horizon = num_frames - 1 and ensure it is positive and divisible by 4

Example fix

# before
{"parameters": {"action_horizon": 16, "num_frames": 16}}
# after
{"parameters": {"action_horizon": 16, "num_frames": 17}}

h, nf = params.get('action_horizon'), params.get('num_frames')
if h is not None and nf is not None:
    assert int(nf) == int(h) + 1, 'num_frames must equal action_horizon + 1'

When it happens

Trigger: action_horizon=16 with num_frames=16; action_horizon=8 with num_frames=32 — any pair where num_frames != action_horizon + 1.

Common situations: Copy-pasting a video-generation config (where num_frames is set independently) into an action request; stale num_frames after tuning action_horizon.

Related errors

• action_horizon must be a positive integer
• Cosmos3 action num_frames must be greater than 1
• Cosmos3 action_horizon must be divisible by 4 so num_frames
• num_frames must be positive
• Cosmos3 action input accepts one image field; use a list or

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