AUTOMATIC1111/stable-diffusion-webui · error · RuntimeError

Unknown checkpoint: {x}

Error message

Unknown checkpoint: {x}

What it means

The checkpoint axis handler apply_checkpoint resolves each value through modules.sd_models.get_closet_checkpoint_match, which fuzzy-matches against checkpoints known to the model list (by filename, hash, or title). A None result means no installed/loaded checkpoint matches, so it raises RuntimeError naming the unmatched value.

Source

Thrown at scripts/xyz_grid.py:79

    # Rebuild the prompt with the tokens in the order we want
    prompt_tmp = ""
    for idx, part in enumerate(prompt_parts):
        prompt_tmp += part
        prompt_tmp += x[idx]
    p.prompt = prompt_tmp + p.prompt


def confirm_samplers(p, xs):
    for x in xs:
        if x.lower() not in sd_samplers.samplers_map:
            raise RuntimeError(f"Unknown sampler: {x}")


def apply_checkpoint(p, x, xs):
    info = modules.sd_models.get_closet_checkpoint_match(x)
    if info is None:
        raise RuntimeError(f"Unknown checkpoint: {x}")
    p.override_settings['sd_model_checkpoint'] = info.name


def confirm_checkpoints(p, xs):
    for x in xs:
        if modules.sd_models.get_closet_checkpoint_match(x) is None:
            raise RuntimeError(f"Unknown checkpoint: {x}")


def confirm_checkpoints_or_none(p, xs):
    for x in xs:
        if x in (None, "", "None", "none"):
            continue

        if modules.sd_models.get_closet_checkpoint_match(x) is None:
            raise RuntimeError(f"Unknown checkpoint: {x}")

View on GitHub (pinned to 82a973c043)

Solutions

1. Verify the file exists under a configured models/Stable-diffusion path and press the refresh button (or restart) so the checkpoint list is rebuilt.
2. Use the exact checkpoint filename shown in the UI dropdown, including the .safetensors/.ckpt extension.
3. A substring or hash also works: pass a distinctive filename fragment or the model's sha256 short hash.
4. For API callers, GET /sdapi/v1/sd-models first and validate axis values against the returned model names.

Example fix

# before
axis_values = "v1-5-pruned.ckpt, sd_xl_base.safetensors"  # sd_xl_base not installed -> RuntimeError

# after
axis_values = "v1-5-pruned.ckpt, dreamshaper_8.safetensors"  # both files present in models dir

import modules.sd_models as sd_models

def validate_checkpoint_axis(xs: list[str]) -> None:
    for x in xs:
        if sd_models.get_closet_checkpoint_match(x) is None:
            available = [c.title for c in sd_models.checkpoints_list.values()]
            raise ValueError(f"Checkpoint '{x}' not found. Available: {available}")

def checkpoint_exists(name: str) -> bool:
    """True when name resolves to an installed checkpoint (filename, substring, or hash)."""
    return isinstance(name, str) and sd_models.get_closet_checkpoint_match(name) is not None

try:
    apply_checkpoint(p, x, xs)
except RuntimeError as e:
    if "Unknown checkpoint" in str(e):
        keep_default_checkpoint(p)  # fallback: continue with currently selected model
    else:
        raise

When it happens

Trigger: Using the 'Checkpoint' axis type with a value that matches no entry in the webui's checkpoint list: a misspelled filename, a hash for a model not present in any model path, or a model that was moved/deleted on disk without refreshing the checkpoint list.

Common situations: Models directory changed or models on an unmounted drive; models shared via symlink with stale model list cache; API calls hardcoding checkpoint filenames from another machine; version updates that changed matching behavior or the model list was never refreshed after adding files.

Related errors

• Prompt S/R did not find {xs[0]} in prompt or negative prompt
• Unknown sampler: {x}
• Lora layer {self.network_key} matched a layer with unsupport
• Could not find a module type (out of {', '.join([x.__class__
• Sampler not found

AI-assisted analysis of AUTOMATIC1111/stable-diffusion-webui@82a973c043 (2026-08-14). Data as JSON: /api/errors/a68034fdfed38f58. Report an issue: GitHub.