invoke-ai/InvokeAI · error · ValueError

Unknown backbone '{name}'. Available: {list(PIPELINE_REGISTR

Error message

Unknown backbone '{name}'. Available: {list(PIPELINE_REGISTRY.keys())}

What it means

get_config resolves a backbone name to a DiffusionPipelineConfig from PIPELINE_REGISTRY. An unknown name raises ValueError listing all registered backbones. This is the entry-point validation for load_pipeline.

Source

Thrown at invokeai/backend/pid/_src/inference/pipeline_registry.py:174

        spatial_compression=8,
        # ZImage-Turbo shares ZImage's VAE/latent convention. Runtime values are
        # read from pipeline.vae.config by denormalize_latent().
        vae_scale_factor=0.0,
        vae_shift_factor=0.0,
        default_resolution=(1024, 1024),
        # The model card describes Turbo as an 8-NFE distilled model. Diffusers'
        # example uses num_inference_steps=9, yielding 8 non-zero scheduler jumps
        # followed by the terminal sigma=0 sample.
        default_num_inference_steps=9,
        default_guidance_scale=0.0,
        extra_generate_kwargs={"max_sequence_length": 512},
    ),
}


def get_config(name: str) -> DiffusionPipelineConfig:
    if name not in PIPELINE_REGISTRY:
        raise ValueError(f"Unknown backbone '{name}'. Available: {list(PIPELINE_REGISTRY.keys())}")
    return PIPELINE_REGISTRY[name]


# ---------------------------------------------------------------------------
# Pipeline loading
# ---------------------------------------------------------------------------


def load_pipeline(
    name: str, model_id: Optional[str] = None, dtype=torch.bfloat16, device: str = "cuda", cpu_offload: bool = False
):
    """Dynamically import and load a diffusers pipeline.

    Args:
        cpu_offload: If True, use enable_model_cpu_offload() instead of .to(device).
            Keeps model weights on CPU and only moves the active component to GPU during
            forward pass. Essential for large models (Flux2, QwenImage, etc.) that exceed
            single-GPU VRAM when all components are loaded simultaneously.

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Use one of the names printed in 'Available:' from PIPELINE_REGISTRY.keys().
2. Fix the casing/spelling in your config or call site.
3. For custom pipelines, register the config in PIPELINE_REGISTRY (or import its registration module) before calling load_pipeline.

Example fix

// before
load_pipeline('RAE-2k')
// after
load_pipeline('rae')  # a key listed in PIPELINE_REGISTRY

from invokeai.backend.pid._src.inference.pipeline_registry import PIPELINE_REGISTRY
if name not in PIPELINE_REGISTRY:
    raise ValueError(f'unknown backbone {name!r}; available: {sorted(PIPELINE_REGISTRY)}')

def is_registered_backbone(name: str) -> bool:
    from invokeai.backend.pid._src.inference.pipeline_registry import PIPELINE_REGISTRY
    return name in PIPELINE_REGISTRY

try:
    cfg = get_config(name)
except ValueError as e:
    logger.error('Unknown backbone: %s', e)
    raise SystemExit(f'Pick one of: {sorted(PIPELINE_REGISTRY.keys())}') from e

When it happens

Trigger: Calling get_config(name) or load_pipeline(name, ...) with a backbone string not in PIPELINE_REGISTRY — typos, old names removed in a refactor, or custom backbones never registered.

Common situations: Config files referencing a backbone id from an older library version; case mismatch ('Rae' vs 'rae'); forgetting to import/execute the module that registers a custom backbone.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unknown ckpt_type {ckpt_type!r}. Valid: {VALID_CKPT_TYPES}
• Unsupported PiD backbone: {backbone!r}
• {args} is not a value argument list for syslog logging
• please provide filename for file logging using format 'file=
• please provide destination for http logging using format 'ht

AI-assisted analysis of invoke-ai/InvokeAI@0b6a024f2f (2026-08-29). Data as JSON: /api/errors/24e230d293a11f3c. Report an issue: GitHub.