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.

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

• attention_head_dim must be positive.
• condition URI must be a non-empty string
• video block token count must be positive
• video block token counts and timestamps must align
• ffn_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.

Appendix: 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)