{"record":{"id":"da50217b40a0d361","repo":"sgl-project/sglang","slug":"minimaxh3visualencodingstage-cannot-encode-materia","errorCode":null,"errorMessage":"MiniMaxH3VisualEncodingStage cannot encode material chains {unsupported}","messagePattern":"MiniMaxH3VisualEncodingStage cannot encode material chains (.+?)","errorType":"validation","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/stages/visual_encoding.py","lineNumber":204,"sourceCode":"                    f\"in {MINIMAX_H3_FL2VA_KEYFRAME_SIGNATURES!r}, got \"\n                    f\"{frame_indices!r}\"\n                )\n        elif keyframe_materials:\n            raise ValueError(\n                f\"task {plan.task!r} cannot carry image.target_canvas materials\"\n            )\n        video_chains = {\n            \"video.reference_preserve\",\n            \"video_audio.reference_preserve\",\n        }\n        supported_chains = {\n            \"image.target_canvas\",\n            \"image.reference_preserve\",\n            *video_chains,\n        }\n        unsupported = sorted(chains - supported_chains)\n        if unsupported:\n            raise NotImplementedError(\n                \"MiniMaxH3VisualEncodingStage cannot encode material chains \"\n                f\"{unsupported}\"\n            )\n        # One VAE dtype toggle for every visual condition in the request.\n        with minimax_h3_scoped_encode_fp32(self.video_vae):\n            if keyframe_materials:\n                self._encode_target_keyframes(batch, plan)\n            if \"image.reference_preserve\" in chains:\n                self._encode_reference_image(batch, plan)\n            if chains & video_chains:\n                self._encode_reference_video(batch, plan)\n\n    def _encode_target_keyframes(self, batch: Req, plan) -> None:\n        if MINIMAX_H3_KEYFRAME_COND_ROWS_EXTRA_KEY in batch.extra:\n            return\n        from sglang.multimodal_gen.runtime.pipelines_core.stages.model_specific_stages.minimax_h3.canvas import (\n            minimax_h3_prepared_keyframes,\n        )","sourceCodeStart":186,"sourceCodeEnd":222,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/stages/visual_encoding.py#L186-L222","documentation":"MiniMaxH3VisualEncodingStage validates the material chains present in a request against a fixed allow-list (image.target_canvas, image.reference_preserve, plus supported video chains) before encoding. If the request contains any other material chain identifier, the stage raises NotImplementedError listing the unsupported chains. This is a capability gate: the visual encoder simply has no code path to encode those materials.","triggerScenarios":"Calling the MiniMax H3 visual encoding pipeline with a request plan whose material chains include anything outside the supported set, e.g. a typo'd chain name like 'image.target_canvos' or a new/unsupported condition type such as 'audio.background'. The _encode_keyframes_from_plan path computes chains - supported_chains and any non-empty remainder triggers it.","commonSituations":"Upgrading the multimodal_gen runtime to a version where chain names were renamed; hand-building request payloads with incorrect chain strings; passing a material type the model variant doesn't support (e.g. using a video-only chain on a keyframe task).","solutions":["Check the error's list of unsupported chains and remove or rename them in the request payload","Compare against the supported_chains set in visual_encoding.py to see exactly which chains are allowed for this stage","If the chain should be supported, verify you're on a recent enough version and that your task profile allows that condition type","Add support in the stage for the new chain if it's a genuine new feature"],"exampleFix":"// before\nplan = {\"chains\": [\"image.target_canvas\", \"image.depth_canny\"]}\n\n// after\nplan = {\"chains\": [\"image.target_canvas\", \"image.reference_preserve\"]}","handlingStrategy":"validation","validationCode":"SUPPORTED = {\"image.target_canvas\", \"image.reference_preserve\"}  # plus task's video chains\nchains = {c for c in request.get(\"chains\", []) if c.startswith(\"image.\")}\nbad = chains - SUPPORTED\nif bad:\n    raise ValueError(f\"remove unsupported chains: {sorted(bad)}\")","typeGuard":"def has_only_supported_chains(chains: list[str]) -> bool:\n    supported = {\"image.target_canvas\", \"image.reference_preserve\"}\n    return all(c in supported or not c.startswith(\"image.\") for c in chains)","tryCatchPattern":"catch NotImplementedError around the encode call and surface the unsupported chain list to the caller as a request-format error","preventionTips":["Construct requests through the task profile's condition rules instead of raw chain strings","Log the request's chain set before submission in dev builds"],"tags":["minimax-h3","visual-encoding","unsupported-feature","validation"],"backgroundTag":"unsupported-operation","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}