{"record":{"id":"1066e6afadeaaa85","repo":"sgl-project/sglang","slug":"for-modality-when-providing-a-processor-output","errorCode":null,"errorMessage":"For {modality}, when providing a 'processor_output' or 'precomputed_embedding', you must pass exactly one item; received {len(data_list)} items (formatted at indices {formatted_indices}).","messagePattern":"For (.+?), when providing a 'processor_output' or 'precomputed_embedding', you must pass exactly one item; received (.+?) items \\(formatted at indices (.+?)\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/multimodal/processors/base_processor.py","lineNumber":1055,"sourceCode":"        return futures, task_info\n\n    @staticmethod\n    def _validate_one_modality(modality: Modality, data_list: Optional[list]):\n        if data_list is None:\n            return\n        if not isinstance(data_list, list):\n            raise TypeError(\n                f\"{modality.name} must be a list or None, got {type(data_list)}\"\n            )\n\n        formatted_indices = []\n        for idx, item in enumerate(data_list):\n            if BaseMultimodalProcessor._is_preprocessed_input(item):\n                formatted_indices.append(idx)\n\n        if formatted_indices:\n            if len(data_list) != 1:\n                raise ValueError(\n                    f\"For {modality}, when providing a 'processor_output' or \"\n                    f\"'precomputed_embedding', you must pass exactly one item; \"\n                    f\"received {len(data_list)} items (formatted at indices {formatted_indices}).\"\n                )\n\n    @staticmethod\n    def validate_mm_data(\n        image_data: Optional[list] = None,\n        video_data: Optional[list] = None,\n        audio_data: Optional[list] = None,\n    ):\n        \"\"\"\n        Validate multimodal input lists per modality.\n\n        Rule per modality (image/video/audio):\n        - Either the list has exactly one item and that single item is a dict with\n          format in {\"processor_output\", \"precomputed_embedding\"};\n        - Or, the list contains only \"normal\" items (i.e., does not include any","sourceCodeStart":1037,"sourceCodeEnd":1073,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/multimodal/processors/base_processor.py#L1037-L1073","documentation":"When a modality list contains a 'preprocessed' item (processor_output or precomputed_embedding), _validate_one_modality requires that list to have exactly one element. Mixing precomputed embeddings with additional raw items is ambiguous and rejected.","triggerScenarios":"Passing something like {'images': [precomputed_item, raw_pil_image]} — i.e. a precomputed embedding alongside other images in the same modality list.","commonSituations":"Caching embeddings per prompt then appending a new raw image; migrating from single-image to multi-image prompts while keeping the precomputed path; batch payloads reusing one embedding for several slots.","solutions":["Split the request: send the precomputed item alone, and raw images in a separate request","If all items are precomputed of the same shape, check the current API for a batched precomputed format; otherwise send sequentially","Drop the precomputed item and send raw media so the processor recomputes everything consistently"],"exampleFix":"// before\nmm_data = {'images': [{'precomputed_embedding': emb}, pil_img]}\n// after\nr1 = processor.process_mm_data_async({'images': [{'precomputed_embedding': emb}]}, ...)\nr2 = processor.process_mm_data_async({'images': [pil_img]}, ...)","handlingStrategy":"validation","validationCode":"for mod, lst in mm_data.items():\n    if lst and any('precomputed_embedding' in it or 'processor_output' in it for it in lst if isinstance(it, dict)):\n        assert len(lst) == 1, 'precomputed items must be sent one per request'","typeGuard":"def is_precomputed(item):\n    return isinstance(item, dict) and ('precomputed_embedding' in item or 'processor_output' in item)","tryCatchPattern":null,"preventionTips":["Never mix precomputed embeddings with raw media in one modality list","Invalidate cached embeddings when the prompt's media set changes"],"tags":["multimodal","precomputed-embedding","input-validation"],"backgroundTag":"mixed-precomputed-and-raw-input","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}