{"record":{"id":"69634b6167308102","repo":"sgl-project/sglang","slug":"cosmos3-observation-image-arrays-must-have-shape","errorCode":null,"errorMessage":"Cosmos3 observation image arrays must have shape [H, W] or [H, W, C], got {tuple(item.shape)}","messagePattern":"Cosmos3 observation image arrays must have shape \\[H, W\\] or \\[H, W, C\\], got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":400,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/entrypoints/action/cosmos3.py","lineNumber":101,"sourceCode":"            )\n        image = next(iter(images.values()))\n\n    if isinstance(image, (list, tuple)):\n        images = list(image)\n    elif isinstance(image, np.ndarray) and image.ndim == 4:\n        images = list(image)\n    else:\n        images = [image]\n\n    normalized_images: list[Any] = []\n    for item in images:\n        if not isinstance(item, np.ndarray):\n            normalized_images.append(item)\n            continue\n        if item.dtype != np.uint8:\n            raise ValueError(\"Cosmos3 observation image arrays must use uint8 dtype\")\n        if item.ndim not in (2, 3):\n            raise ValueError(\n                \"Cosmos3 observation image arrays must have shape [H, W] \"\n                f\"or [H, W, C], got {tuple(item.shape)}\"\n            )\n        normalized_images.append(Image.fromarray(item))\n    return normalized_images\n\n\ndef _action_prompt(prompt: Any, batch_size: int) -> str | list[str]:\n    if isinstance(prompt, str):\n        return prompt if batch_size == 1 else [prompt] * batch_size\n    if not isinstance(prompt, (list, tuple)) or not prompt:\n        raise ValueError(\"Cosmos3 action prompt must be a string or non-empty list\")\n    if not all(isinstance(item, str) for item in prompt):\n        raise ValueError(\"Cosmos3 action prompt list must contain only strings\")\n    prompts = list(prompt)\n    if len(prompts) == 1 and batch_size > 1:\n        prompts *= batch_size\n    if len(prompts) != batch_size:","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/entrypoints/action/cosmos3.py#L83-L119","documentation":"numpy image arrays for Cosmos3 must be 2D grayscale [H, W] or 3D [H, W, C]; other ranks raise this ValueError with the offending shape. Note [B,H,W,C] batched arrays are handled elsewhere — per-item arrays here must be single images.","triggerScenarios":"Passing a [B,H,W,C] batched array that ends up iterated per-item incorrectly, a flattened [H*W] vector, [C,H,W] channel-first tensor converted to numpy, or an [H,W,C,T] video clip.","commonSituations":"Images converted from torch tensors keeping channel-first layout; video frames with an extra time dimension; already-batched arrays reaching a code path expecting single images.","solutions":["Transpose/reshape to [H,W] or [H,W,C]: arr = arr.transpose(1,2,0) for CHW->HWC","Remove batch/time dims: arr.squeeze() or arr[0] / arr[:, t]","For batches, pass a list of [H,W,C] uint8 arrays"],"exampleFix":"# before\nimage = chw_tensor.numpy()  # shape [3, 224, 224] -> error\n\n# after\nimage = chw_tensor.permute(1, 2, 0).numpy().astype(np.uint8)  # [224, 224, 3]","handlingStrategy":"type-guard","validationCode":"import numpy as np\ndef ensure_hwc_uint8(arr: np.ndarray) -> np.ndarray:\n    assert arr.ndim in (2, 3), f\"bad image rank {arr.shape}\"\n    if arr.ndim == 3 and arr.shape[0] in (1, 3) and arr.shape[0] < arr.shape[-1]:\n        arr = arr.transpose(1, 2, 0)  # CHW -> HWC heuristic\n    return ensure_uint8(arr)","typeGuard":"def is_valid_image_shape(a) -> bool:\n    return not isinstance(a, np.ndarray) or (a.dtype == np.uint8 and a.ndim in (2, 3))","tryCatchPattern":null,"preventionTips":["Convert torch CHW tensors with .permute(1,2,0) before .numpy()","Squeeze batch/time dims explicitly rather than relying on downstream handling","Unit-test observation shapes against the API contract"],"tags":["cosmos3","numpy","shape","image-input"],"backgroundTag":"image-shape-invalid","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}