sgl-project/sglang · error · ValueError

Invalid layerwise offload component name: {raw_component}.

Error message

Invalid layerwise offload component name: {raw_component}.

What it means

Raised by normalize_layerwise_offload_components when an element of the layerwise-offload component list is not a string. The API accepts a single string or a list of strings (each optionally comma-separated), and any non-string element (int, None, enum) is rejected before normalization.

Source

Thrown at python/sglang/multimodal_gen/runtime/managers/memory_managers/layerwise_offload_components.py:203

def expand_layerwise_offload_component_group(component_name: str) -> tuple[str, ...]:
    if component_name == LAYERWISE_OFFLOAD_DEFAULT_GROUP:
        return LAYERWISE_OFFLOAD_DEFAULT_GROUP_COMPONENTS
    return (component_name,)


def normalize_layerwise_offload_components(
    component_names: str | Sequence[str] | None,
) -> list[str] | None:
    if component_names is None:
        return None

    raw_components = (
        [component_names] if isinstance(component_names, str) else component_names
    )
    normalized_components: list[str] = []
    for raw_component in raw_components:
        if not isinstance(raw_component, str):
            raise ValueError(
                f"Invalid layerwise offload component name: {raw_component}."
            )
        for component_name in raw_component.split(","):
            component_name = component_name.strip().replace("-", "_").lower()
            if not component_name:
                continue
            for expanded_component_name in expand_layerwise_offload_component_group(
                component_name
            ):
                if expanded_component_name == LAYERWISE_OFFLOAD_ALL_COMPONENTS:
                    return [LAYERWISE_OFFLOAD_ALL_COMPONENTS]
                if expanded_component_name not in normalized_components:
                    normalized_components.append(expanded_component_name)

    return normalized_components or None

View on GitHub (pinned to 0132848349)

Solutions

  1. Ensure every element of component_names is a str, e.g. [str(c) for c in component_names]
  2. Fix the config source: quote the component names in YAML/JSON so they parse as strings
  3. If passing an enum, use its .value

Example fix

// before
configure_layerwise_offload_modules([None, "dit"])
// after
configure_layerwise_offload_modules(["dit"])
Defensive patterns

Strategy: type-guard

Validate before calling

components = [c for c in raw_components if c is not None]
assert all(isinstance(c, str) for c in components), components

Type guard

def is_component_list(v) -> TypeGuard[list[str]]:
    return isinstance(v, list) and all(isinstance(x, str) for x in v)

Prevention

When it happens

Trigger: Calling configure_layerwise_offload_modules / get_layerwise_offload_component_names_for_pipeline / residency_mode with a list containing non-str entries, e.g. component_names=[None, 'dit', 3] or passing an enum/config object instead of its string name.

Common situations: Config files (YAML/JSON) where the component field is parsed as int/bool/null, or passing a config dataclass attribute directly instead of the string name; also passing a tuple of mixed types.

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

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