What causes "pipeline_config_cls must inherit from PipelineConfig" in sgl-project/sglang?

Subclass PipelineConfig for your config class and pass it as the second argument

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.

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)

Solutions

Subclass PipelineConfig for your config class and pass it as the second argument
Double-check argument order: (pipeline_cls, pipeline_config_cls)
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

Use keyword args to avoid positional swaps
Subclass PipelineConfig rather than writing a bare dataclass
Test registration in CI so config-class mistakes surface early

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.