unslothai/unsloth · error · FileNotFoundError

Local pipeline directory has no model_index.json: {repo_id}

Error message

Local pipeline directory has no model_index.json: {repo_id}

What it means

FileNotFoundError from the pipeline branch: repo_id is an existing local directory, but it has no model_index.json - the file that makes a directory a loadable diffusers pipeline. Without it, from_pretrained would fail deep in the load after chat eviction, so it is caught in the network-free validation instead (modular_model_index.json is accepted only in the modular-allowing variant of the check, not here).

Source

Thrown at studio/backend/core/inference/diffusion.py:1700

                raise ValueError("a .gguf checkpoint needs model_kind 'gguf', not 'single_file'.")
            # A single-file load must name a real .safetensors, else it evicts chat then fails in background.
            if kind == "single_file" and not gguf_filename.lower().endswith(".safetensors"):
                raise ValueError(
                    f"'{gguf_filename}' is not a loadable single-file checkpoint "
                    f"(expected a .safetensors name; use a .gguf name for a GGUF load)."
                )
            if local_root.exists():
                resolve_local_gguf_child(local_root, gguf_filename)
            elif path_shaped:
                raise FileNotFoundError(f"Local model path does not exist: {repo_id}")
        else:  # pipeline
            if gguf_filename:
                raise ValueError(
                    "a 'pipeline' load takes a full diffusers repo, not a single-file name."
                )
            if local_root.exists():
                if not (local_root / "model_index.json").exists():
                    raise FileNotFoundError(
                        f"Local pipeline directory has no model_index.json: {repo_id}"
                    )
            elif path_shaped:
                raise FileNotFoundError(f"Local model path does not exist: {repo_id}")
            elif repo_id.upper().endswith("-GGUF"):
                # A remote "*-GGUF" id is not a pipeline; reject here instead of evicting chat then failing.
                raise ValueError(
                    f"'{repo_id}' is a single-file GGUF repo; load it with model_kind 'gguf' "
                    f"and a .gguf filename, not as a full pipeline."
                )
        return fam

    def preflight_base_access(
        self,
        repo_id: str,
        fam: Optional[DiffusionFamily],
        *,
        gguf_filename: Optional[str] = None,

View on GitHub (pinned to 203007d190)

Solutions

Point at a complete diffusers snapshot - re-download the pipeline repo fully so model_index.json lands at the root.
If the directory holds GGUF/single-file checkpoints, load with model_kind='gguf'/'single_file' and the file name instead.
Check for a nested layout: sometimes the real pipeline dir is one level down (e.g. <root>/flux-dev/), pass that inner directory.

Example fix

# before
manager.validate_load_request(repo_id="/data/flux-download")
# FileNotFoundError: Local pipeline directory has no model_index.json: /data/flux-download

# after: either the inner complete snapshot, or a single-file load
manager.validate_load_request(repo_id="/data/flux-download/snapshots/abc123")
# or: model_kind="single_file", gguf_filename="flux-dev.safetensors"

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path

def is_pipeline_dir(repo_id: str) -> bool:
    root = Path(repo_id).expanduser()
    return root.is_dir() and (root / "model_index.json").is_file()

Try / catch

try:
    fam = manager.validate_load_request(repo_id=r)
except FileNotFoundError as e:
    if "no model_index.json" in str(e):
        suggest_single_file_load_or_redownload(r)
    else:
        raise

Prevention

Download pipeline repos as complete snapshots (hf download / snapshot_download), never file-by-file.
For local model scanners, treat only model_index.json-bearing directories as pipeline loads; route the rest to gguf/single-file kinds.
Check for nested snapshot directories and pass the innermost complete one.

When it happens

Trigger: Passing a local directory as a pipeline load when the directory is a GGUF folder, a raw weights folder, an incomplete download, or a single-file checkpoint directory - anything without model_index.json at its root.

Common situations: User points at the folder that contains their .gguf files assuming any model dir works; download interrupted before model_index.json was fetched; pointing at a single-file .safetensors download directory rather than a full pipeline snapshot.

Related errors

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/8c42a35205898211. Report an issue: GitHub.