sgl-project/sglang · error · TypeError

pipeline_config_cls must inherit from PipelineConfig

Error message

pipeline_config_cls must inherit from PipelineConfig

What it means

The second validation in register_pipeline requires pipeline_config_cls to be a subclass of PipelineConfig. Passing any other class (a dataclass, dict wrapper, or the pipeline class again) raises TypeError before any registry mutation happens.

Solutions

  1. Subclass PipelineConfig for your config class and pass it as the second argument
  2. Double-check argument order: (pipeline_cls, pipeline_config_cls)
  3. Re-run registration after fixing; the checks run before the registry is modified, so state stays clean

Example fix

# before
@dataclass
class MyConfig: ...
register_pipeline(MyPipeline, MyConfig)
# after
from sglang.multimodal_gen.pipelines import PipelineConfig
class MyConfig(PipelineConfig): ...
register_pipeline(MyPipeline, MyConfig)
Defensive patterns

Strategy: type-guard

Validate before calling

from sglang.multimodal_gen.pipelines import PipelineConfig
assert issubclass(MyConfig, PipelineConfig), "config must subclass PipelineConfig"

Type guard

def is_pipeline_config(cls) -> bool:
    from sglang.multimodal_gen.pipelines import PipelineConfig
    return isinstance(cls, type) and issubclass(cls, PipelineConfig)

Try / catch

try:
    register_pipeline(pipeline_cls=MyPipeline, pipeline_config_cls=MyConfig)
except TypeError as e:
    if "PipelineConfig" in str(e):
        raise RuntimeError(f"{MyConfig} must inherit PipelineConfig") from e
    raise

Prevention

When it happens

Trigger: Calling register_pipeline(PipelineCls, ConfigCls) where ConfigCls is not a PipelineConfig subclass — e.g. a plain dataclass or the model class itself.

Common situations: Swapping the two positional arguments; writing a custom config as a @dataclass instead of subclassing PipelineConfig; copying a diffusers registration snippet into sglang.

Related errors


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

Appendix: source

Thrown at python/sglang/multimodal_gen/registry.py:391

            _MODEL_NAME_DETECTORS.append((model_id, detector))
    return model_id


def register_pipeline(
    pipeline_cls: Type[ComposedPipelineBase],
    *,
    sampling_param_cls: Any,
    pipeline_config_cls: Type[PipelineConfig],
    hf_model_paths: Optional[List[str]] = None,
    model_detectors: Optional[List[Callable[[str], bool]]] = None,
    overwrite: bool = False,
) -> None:
    """Register an out-of-tree native diffusion pipeline and its configs."""
    _discover_and_register_pipelines()
    if not issubclass(pipeline_cls, ComposedPipelineBase):
        raise TypeError("pipeline_cls must inherit from ComposedPipelineBase")
    if not issubclass(pipeline_config_cls, PipelineConfig):
        raise TypeError("pipeline_config_cls must inherit from PipelineConfig")

    pipeline_name = pipeline_cls.pipeline_name
    existing_pipeline = _PIPELINE_REGISTRY.get(pipeline_name)
    if existing_pipeline is not None and not overwrite:
        raise ValueError(
            f"Pipeline '{pipeline_name}' is already registered; pass overwrite=True to replace it"
        )
    for model_path in hf_model_paths or []:
        if model_path in _MODEL_HF_PATH_TO_NAME and not overwrite:
            raise ValueError(f"Model path '{model_path}' is already registered")
        registered_pipeline = KNOWN_NON_DIFFUSERS_DIFFUSION_MODEL_PATTERNS.get(
            model_path.lower()
        )
        if registered_pipeline is not None and not overwrite:
            raise ValueError(
                f"Model path '{model_path}' is already registered for pipeline "
                f"'{registered_pipeline}'"
            )

View on GitHub (pinned to 0132848349)