unslothai/unsloth · error · FileNotFoundError

Local model path does not exist: {repo_id}

Error message

Local model path does not exist: {repo_id}

What it means

FileNotFoundError from the local-path branch of the gguf/single_file validation: the repo_id is path-shaped (starts with /, ~, ., contains a backslash, or is absolute), it does not exist on disk, and the kind is gguf or single_file. Failing here prevents the route from evicting the resident chat model for a load that cannot find its files.

Source

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

        if kind in ("gguf", "single_file"):
            if not gguf_filename:
                raise ValueError(f"a single-file checkpoint name is required for a '{kind}' load.")
            # Fail a kind/extension mismatch before the handoff: gguf needs .gguf, single_file must not.
            is_gguf_name = gguf_filename.lower().endswith(".gguf")
            if kind == "gguf" and not is_gguf_name:
                raise ValueError("a 'gguf' load requires a .gguf checkpoint name.")
            if kind == "single_file" and is_gguf_name:
                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."
                )

View on GitHub (pinned to 203007d190)

Solutions

1. Verify the path exists: run `ls <path>` (or dir) and fix typos, mount the drive, or update the location.
2. Use an absolute path or ensure the shell/launcher expands '~' before it reaches the API.
3. If the model is remote after all, use the 'org/name' HF id form instead of a path.

Example fix

# before: directory renamed
manager.validate_load_request(repo_id="~/models/flux-gguf-old",
    model_kind="gguf", gguf_filename="t-Q4.gguf")
# FileNotFoundError: Local model path does not exist: ~/models/flux-gguf-old

# after
manager.validate_load_request(repo_id=str(Path.home() / "models" / "flux-gguf"),
    model_kind="gguf", gguf_filename="t-Q4.gguf")

from pathlib import Path

def local_path_exists(repo_id: str) -> bool:
    try:
        return Path(repo_id).expanduser().exists()
    except OSError:
        return False

try:
    fam = manager.validate_load_request(repo_id=r, model_kind=k, gguf_filename=f)
except FileNotFoundError as e:
    if "Local model path does not exist" in str(e):
        prompt_to_reselect_local_directory(r)
    else:
        raise

When it happens

Trigger: Passing a path-shaped repo_id like '~/models/flux-gguf', 'D:\models\flux', or './checkpoints/x' that does not exist, with model_kind gguf/single_file (with a valid checkpoint name).

Common situations: Model directory moved, renamed, or on an unmounted drive; tilde not expanded because the path came from a config file with a literal '~'; Windows path pasted on Linux or vice versa; typo in the directory name.

Related errors

• {exc}
• a single-file checkpoint name is required for a '{kind}' loa
• a 'gguf' load requires a .gguf checkpoint name.
• a .gguf checkpoint needs model_kind 'gguf', not 'single_file
• Local pipeline directory has no model_index.json: {repo_id}

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