sgl-project/sglang · error · ValueError

Cosmos3 action num_frames must be greater than 1

Error message

Cosmos3 action num_frames must be greater than 1

What it means

When only num_frames is provided to the Cosmos3 action endpoint (no action_horizon), it must be > 1. num_frames represents conditioning frame + generated frames, so num_frames <= 1 leaves no room for any action. The value is int()-coerced before the check.

Source

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

    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")
    if action_mode == "inverse_dynamics" and video_path is None:
        raise ValueError("Cosmos3 inverse_dynamics input requires an observation video")
    if images and video_path is not None:
        raise ValueError("Cosmos3 action requests accept either an image or a video")
    batch_size = len(images) if images else 1
    max_batch_size = max(1, int(getattr(server_args, "batching_max_size", 1)))
    if batch_size > max_batch_size:
        raise ValueError(

View on GitHub (pinned to 0132848349)

Solutions

1. Set num_frames to action_horizon + 1 (e.g. 17 for horizon 16), or use action_horizon instead
2. For image-only policy queries, you still need num_frames/action_horizon compatible with the temporal VAE: (num_frames-1) % 4 == 0

Example fix

# before
{"parameters": {"num_frames": 1}}
# after
{"parameters": {"num_frames": 17}}

nf = params.get('num_frames')
if nf is not None and 'action_horizon' not in params:
    assert int(nf) > 1, 'num_frames must be > 1'

When it happens

Trigger: Passing parameters.num_frames=1 or 0 (or negative) without an action_horizon in a /v1/actions request.

Common situations: Reusing a single-image inference config where num_frames=1; off-by-one confusion treating num_frames as action count; defaults meant for image endpoints.

Related errors

• action_horizon must be a positive integer
• Cosmos3 requires num_frames == action_horizon + 1, got num_f
• num_frames must be positive
• Cosmos3 action input accepts one image field; use a list or
• Cosmos3 observation image arrays must use uint8 dtype

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