sgl-project/sglang · error · NotImplementedError

MiniMaxH3VisualEncodingStage cannot encode material chains {

Error message

MiniMaxH3VisualEncodingStage cannot encode material chains {unsupported}

What it means

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.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/stages/visual_encoding.py:204

                    f"in {MINIMAX_H3_FL2VA_KEYFRAME_SIGNATURES!r}, got "
                    f"{frame_indices!r}"
                )
        elif keyframe_materials:
            raise ValueError(
                f"task {plan.task!r} cannot carry image.target_canvas materials"
            )
        video_chains = {
            "video.reference_preserve",
            "video_audio.reference_preserve",
        }
        supported_chains = {
            "image.target_canvas",
            "image.reference_preserve",
            *video_chains,
        }
        unsupported = sorted(chains - supported_chains)
        if unsupported:
            raise NotImplementedError(
                "MiniMaxH3VisualEncodingStage cannot encode material chains "
                f"{unsupported}"
            )
        # One VAE dtype toggle for every visual condition in the request.
        with minimax_h3_scoped_encode_fp32(self.video_vae):
            if keyframe_materials:
                self._encode_target_keyframes(batch, plan)
            if "image.reference_preserve" in chains:
                self._encode_reference_image(batch, plan)
            if chains & video_chains:
                self._encode_reference_video(batch, plan)

    def _encode_target_keyframes(self, batch: Req, plan) -> None:
        if MINIMAX_H3_KEYFRAME_COND_ROWS_EXTRA_KEY in batch.extra:
            return
        from sglang.multimodal_gen.runtime.pipelines_core.stages.model_specific_stages.minimax_h3.canvas import (
            minimax_h3_prepared_keyframes,
        )

View on GitHub (pinned to 0132848349)

Solutions

1. Check the error's list of unsupported chains and remove or rename them in the request payload
2. Compare against the supported_chains set in visual_encoding.py to see exactly which chains are allowed for this stage
3. If the chain should be supported, verify you're on a recent enough version and that your task profile allows that condition type
4. Add support in the stage for the new chain if it's a genuine new feature

Example fix

// before
plan = {"chains": ["image.target_canvas", "image.depth_canny"]}

// after
plan = {"chains": ["image.target_canvas", "image.reference_preserve"]}

SUPPORTED = {"image.target_canvas", "image.reference_preserve"}  # plus task's video chains
chains = {c for c in request.get("chains", []) if c.startswith("image.")}
bad = chains - SUPPORTED
if bad:
    raise ValueError(f"remove unsupported chains: {sorted(bad)}")

def has_only_supported_chains(chains: list[str]) -> bool:
    supported = {"image.target_canvas", "image.reference_preserve"}
    return all(c in supported or not c.startswith("image.") for c in chains)

catch NotImplementedError around the encode call and surface the unsupported chain list to the caller as a request-format error

When it happens

Trigger: 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.

Common situations: 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).

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• MiniMax-H3 adaln_t_table must have shape [N, D] with N >= 2,
• MiniMax H3 AdaLN cache has invalid timestep plans
• TP size must be positive.
• num_attention_heads must be positive.
• hidden_size must be positive.

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