sgl-project/sglang · error · ValueError

Kimi-K3 encoder preprocessing needs an image processor

Error message

Kimi-K3 encoder preprocessing needs an image processor

What it means

Kimi-K3's encoder preprocessing requires an image processor; passing image_processor=None to preprocess_mm_for_encoder() raises ValueError. The processor is stored and later used by prepare_kimi_k3_encoder_inputs and CPU/GPU feature materialization.

Source

Thrown at python/sglang/srt/models/kimi_k3.py:3342

            raise AttributeError(
                "DSPARK layer capture is not available in encoder-only mode"
            )
        self.language_model.set_dspark_layers_to_capture(layer_ids)

    def preprocess_mm_for_encoder(
        self,
        mm_data,
        modality,
        config,
        *,
        image_processor=None,
        use_gpu_preprocessing=False,
    ):
        """Prepare per-image raw inputs for owner-side EPD preprocessing."""
        if modality != Modality.IMAGE:
            raise ValueError("Kimi-K3 encoder mode supports image input only")
        if image_processor is None:
            raise ValueError("Kimi-K3 encoder preprocessing needs an image processor")

        from sglang.srt.multimodal.kimi_k3_image_processing import (
            prepare_kimi_k3_encoder_inputs,
        )

        self._encoder_image_processor = image_processor
        return prepare_kimi_k3_encoder_inputs(
            mm_data,
            image_processor,
            use_gpu_preprocessing=use_gpu_preprocessing,
        )

    def get_image_feature(self, items: List[MultimodalDataItem]) -> torch.Tensor:
        device = self.vision_tower.device
        target_dtype = self.vision_tower.patch_embed.proj.weight.dtype
        image_grid_thws = []
        for item in items:
            grid_thw = item.model_specific_data.get("image_grid_thw")

View on GitHub (pinned to 0132848349)

Solutions

1. Load the model's HF image processor and pass it into the call
2. Initialize the processor at model load time and thread it through the preprocessing path
3. Add a startup assertion that the processor exists before serving

Example fix

// before
model.preprocess_mm_for_encoder(modality=m, data=d, image_processor=None)

// after
model.preprocess_mm_for_encoder(modality=m, data=d, image_processor=processor)

if image_processor is None:
    image_processor = load_kimi_k3_image_processor(model_config)
assert image_processor is not None

def has_image_processor(p) -> bool:
    return p is not None and hasattr(p, "preprocess")

When it happens

Trigger: Calling preprocess_mm_for_encoder(...) without supplying image_processor, e.g. a caller that lazily loads processors or assumed the model holds its own.

Common situations: Custom serving harnesses that build the processor conditionally; encoder-only deployments where the processor was not initialized alongside the model.

Related errors

• Usage: sglang serve --model-path <model-name-or-path> [addit
• Error: --model-path is required. Please provide the path to
• v_cache must be provided
• q must be provided unless qv is provided with only_qv=True
• mask_block_cnt and mask_block_idx must be provided for block

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