sgl-project/sglang · error · ValueError

Model directory {model_path} does not contain a transformer/

Error message

Model directory {model_path} does not contain a transformer/ directory.

What it means

Fallback branch of verify_model_config_and_directory for model_index.json without component keys: it then requires a literal transformer/ subdirectory under model_path. Missing directory raises ValueError.

Source

Thrown at python/sglang/multimodal_gen/runtime/utils/hf_diffusers_utils.py:738

        and all(isinstance(item, str) for item in value)
    ]
    if component_keys:
        missing_components = [
            component_key
            for component_key in component_keys
            if not os.path.exists(os.path.join(model_path, component_key))
        ]
        if missing_components:
            missing_str = ", ".join(missing_components)
            raise ValueError(
                f"Model directory {model_path} is missing required component "
                f"directories: {missing_str}."
            )
    else:
        transformer_dir = os.path.join(model_path, "transformer")
        vae_dir = os.path.join(model_path, "vae")
        if not os.path.exists(transformer_dir):
            raise ValueError(
                f"Model directory {model_path} does not contain a transformer/ directory."
            )
        if not os.path.exists(vae_dir):
            raise ValueError(
                f"Model directory {model_path} does not contain a vae/ directory."
            )
    return cast(dict[str, Any], config)


def _resolve_remote_repo_model_index_path(model_name_or_path: str) -> str:
    """Return a local path to a remote repo's ``model_index.json``"""
    try:
        # Cache-aware: no local_dir, so the selected Hub reuses its cache and
        # revalidates the remote file when online.
        return hf_hub_download(repo_id=model_name_or_path, filename="model_index.json")
    except EntryNotFoundError:
        # Repo exists but has no model_index.json (single-model repo); let the
        # caller fall through to the single-model path.

View on GitHub (pinned to 0132848349)

Solutions

1. Ensure the directory containing the transformer weights is named 'transformer' (rename 'unet' where applicable)
2. Restore/re-download the missing component
3. Use a proper diffusers repo whose model_index.json declares components so the standard branch applies

Example fix

# before
/model/sd3/unet/...
# after (rename)
mv /model/sd3/unet /model/sd3/transformer

import os
assert os.path.isdir(os.path.join(model_path, 'transformer'))

When it happens

Trigger: Calling the verifier on a minimal/nonstandard model_index.json while the model directory also lacks a transformer/ folder (e.g. text-encoder-only or VAE-only checkpoints, or misnamed folders like 'unet/').

Common situations: Renamed component dirs (unet vs transformer for SD-like models); partial snapshots; pointing at a repo that is not a diffusion transformer pipeline.

Related errors

• Model directory {model_path} is missing required component d
• Z-Image transformer has no `rotary_emb`. It likely loaded vi
• Model path '{model_path}' is already registered for pipeline
• --diffusers-kwargs must be valid JSON. Got: {args.diffusers_
• Model config does not contain a _class_name attribute. Only

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