sgl-project/sglang · error · ValueError

Unknown image_vae_encoding_position: {image_vae_encoding_pos

Error message

Unknown image_vae_encoding_position: {image_vae_encoding_position}

What it means

This error is thrown by add_standard_ti2v_stages in the multimodal generation pipeline when the image_vae_encoding_position argument is neither the built-in 'before_timestep' position nor a value that triggers the dedicated image-VAE stage registration. It signals an unrecognized enum-like string in the text/image-to-video (TI2V) stage composition config. The library validates this setting because the VAE encoding placement determines where the image condition is injected into the denoising pipeline.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/composed_pipeline_base.py:983

                )
            )

        self.add_standard_latent_preparation_stage()
        self.add_standard_timestep_preparation_stage(
            prepare_extra_kwargs=prepare_extra_timestep_kwargs
        )
        if image_vae_encoding_position == "after_latent":
            self.add_stage(
                ImageVAEEncodingStage(
                    vae=self.get_module(image_vae_key),
                    **{
                        "component_name": image_vae_key,
                        **(image_vae_stage_kwargs or {}),
                    },
                )
            )
        elif image_vae_encoding_position != "before_timestep":
            raise ValueError(
                f"Unknown image_vae_encoding_position: {image_vae_encoding_position}"
            )

        if denoising_stage_factory is None:
            self.add_standard_denoising_stage()
        else:
            self.add_stage_factory(
                RoleType.DENOISER,
                denoising_stage_factory,
                denoising_stage_name,
            )

        self.add_standard_decoding_stage()
        return self

    # TODO(will): don't hardcode no_grad
    @torch.no_grad()
    def forward(

View on GitHub (pinned to 0132848349)

Solutions

Check the exact spelling and casing of image_vae_encoding_position against the values handled in composed_pipeline_base.py around the raise (the image_vae stage branch and 'before_timestep')
Set the argument to 'before_timestep' (the no-extra-stage default) or one of the supported stage positions
If you need a new position, extend the if/elif chain in add_standard_ti2v_stages before the raise

Example fix

# before
pipeline.add_standard_ti2v_stages(image_vae_encoding_position="before_timesteps")
# after
pipeline.add_standard_ti2v_stages(image_vae_encoding_position="before_timestep")

Defensive patterns

Strategy: validation

Validate before calling

ALLOWED = {"before_timestep"}  # plus the image_vae stage branch values in add_standard_ti2v_stages
if pos not in ALLOWED:
    raise ConfigError(f"unsupported image_vae_encoding_position: {pos!r}; allowed: {sorted(ALLOWED)}")
pipeline.add_standard_ti2v_stages(image_vae_encoding_position=pos)

Type guard

def is_valid_vae_encoding_position(pos: str) -> bool:
    return isinstance(pos, str) and pos in {"before_timestep"}

Prevention

Centralize pipeline enum values as constants instead of raw strings
Validate config strings at load time before building pipelines

When it happens

Trigger: Calling create_pipeline_stages / add_standard_ti2v_stages with image_vae_encoding_position set to a string other than the supported values (the special-cased stage key or 'before_timestep'), e.g. a typo like 'before_timesteps' or 'after_timestep', or passing None/non-string when the pipeline expects a known position.

Common situations: Typos in pipeline config YAML/CLI, copying a position name from a different framework version where new positions were added/renamed, or upgrading/downgrading sglang where supported values changed.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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