What causes "Unknown sampler: {x}" in AUTOMATIC1111/stable-diffusion-webui?

Use exact names from the webui's sampler dropdown (e.g. 'Euler a', 'DPM++ 2M Karras', 'DDIM'); copy them from the UI rather than typing.

AUTOMATIC1111/stable-diffusion-webui · error · RuntimeError

Unknown sampler: {x}

Error message

Unknown sampler: {x}

What it means

The sampler-axis validation function confirm_samplers runs before the grid is generated and checks every requested sampler name (lowercased) against the sd_samplers.samplers_map registry. If a name is not a registered sampler, generation cannot proceed, so it raises RuntimeError listing the offending value.

Source

Thrown at scripts/xyz_grid.py:73

    # Split the prompt up, taking out the tokens
    for _, token in token_order:
        n = p.prompt.find(token)
        prompt_parts.append(p.prompt[0:n])
        p.prompt = p.prompt[n + len(token):]

    # 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"):

View on GitHub (pinned to 82a973c043)

Solutions

Use exact names from the webui's sampler dropdown (e.g. 'Euler a', 'DPM++ 2M Karras', 'DDIM'); copy them from the UI rather than typing.
Trim whitespace and normalize casing in the axis value list before running.
Print available names at runtime: `from modules import sd_samplers; print(sd_samplers.samplers_map.keys())` and match your list against it.
If a sampler is genuinely missing, update the webui or the extension that provides it.

Example fix

# before
axis_values = "Euler ancestral, DPM2"  # unknown names -> RuntimeError

# after
axis_values = "Euler a, DPM++ 2S a"  # exact registered names

Defensive patterns

Strategy: validation

Validate before calling

from modules import sd_samplers

def validate_sampler_axis(xs: list[str]) -> list[str]:
    unknown = [x for x in xs if x.strip().lower() not in sd_samplers.samplers_map]
    if unknown:
        raise ValueError(f"Unknown samplers: {unknown}; available: {sorted(sd_samplers.samplers_map)}")
    return [x.strip() for x in xs]

Type guard

def is_known_sampler(name: str) -> bool:
    """True when name (case-insensitive, trimmed) is a registered sampler."""
    return isinstance(name, str) and name.strip().lower() in sd_samplers.samplers_map

Try / catch

try:
    confirm_samplers(p, xs)
except RuntimeError as e:
    match = re.search(r"Unknown sampler: (.+)", str(e))
    if match:
        xs = [x for x in xs if x.lower() in sd_samplers.samplers_map]  # drop bad entries
    else:
        raise

Prevention

Source sampler names from sd_samplers.samplers_map programmatically instead of hardcoding.
Strip and lowercase-verify pasted lists before running.
After upgrading the webui, re-validate saved presets that reference sampler names.

When it happens

Trigger: Setting the X/Y/Z axis type to 'Sampler' with a list containing an unknown or misspelled sampler name (e.g. 'Euler a ' with trailing space, 'dpm++ 2M' in wrong casing/format, or a sampler removed/renamed in a newer webui version). Also triggered when a checkpoint or extension registers custom samplers that are not loaded.

Common situations: Version drift: sampler names changed between webui releases (k_* aliases vs display names); tutorials referencing samplers that no longer exist; trailing whitespace or smart quotes from copy-pasting lists; API callers passing sampler IDs from a different backend (e.g. ComfyUI names).

Related errors

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