unslothai/unsloth · error · RuntimeError

The diffusion engine changed while this load was starting. R

Error message

The diffusion engine changed while this load was starting. Retry the load.

What it means

begin_load_on() re-checks, under the same transition lock an engine switch takes, that the engine captured at selection time is still the active one. A concurrent request can transition engines in the gap between selection and load registration; loading then would produce a model nothing can reach (generate/status/unload all resolve through get_active_diffusion_engine()).

Source

Thrown at studio/backend/core/inference/diffusion_engine_router.py:149

            logger.info("diffusion engine: sd_cpp")
        else:
            logger.info("diffusion engine: diffusers (%s)", reason or "selected")
        return get_active_diffusion_engine()


def begin_load_on(expected_engine: Any, start: Callable[[], Any]) -> Any:
    """Run ``start`` under the transition lock, refusing if the engine changed since selection.

    A load route selects its engine, then yields (device probe, arbiter acquire) before it
    registers the load. A second /images/load picking the OTHER engine can transition in that
    gap and unload the still-idle engine this request captured, which would then load a model
    nothing can reach: generate / status / unload and the arbiter's evictor all resolve through
    get_active_diffusion_engine(). Re-checking under the same lock the switch takes makes
    selection and registration one operation.
    """
    with _transition_lock:
        if expected_engine is not get_active_diffusion_engine():
            raise RuntimeError(
                "The diffusion engine changed while this load was starting. Retry the load."
            )
        return start()


def select_and_activate_engine(
    fam: DiffusionFamily,
    *,
    hf_token: Optional[str] = None,
    model_kind: Optional[str] = None,
) -> Any:
    """Pick + activate the engine for loading ``fam`` on this host; return the engine.

    Falls back to diffusers (recording a reason) when the native route is disabled, the device has
    a usable GPU, MPS is not enabled, the family has no native asset, or the binary is unavailable
    -- always BEFORE the slow load, so a fallback never strands a half-native load.
    """
    # Non-GGUF loads run on diffusers only (the native engine consumes single-file GGUF only).

View on GitHub (pinned to 203007d190)

Solutions

1. Retry the whole load: re-select the engine and call begin_load_on again (the error message tells the user to retry)
2. Serialize loads client-side (one load request at a time) when the engine choice matters
3. For API wrappers, treat this RuntimeError as a transient conflict — back off briefly and re-run selection + load

Example fix

# before
engine = get_active_diffusion_engine()
# ... device probe, arbiter acquire (yield point) ...
begin_load_on(engine, start)  # RuntimeError if engine flipped

# after
for attempt in range(3):
    engine = get_active_diffusion_engine()
    try:
        return begin_load_on(engine, start)
    except RuntimeError:
        continue  # engine flipped; re-select and retry

for attempt in range(MAX_RETRIES):
    expected = get_active_diffusion_engine()
    try:
        return begin_load_on(expected, start)
    except RuntimeError as e:
        if "changed while this load was starting" not in str(e):
            raise
        time.sleep(BACKOFF * 2**attempt)  # engine flipped; re-select and retry

When it happens

Trigger: Two /images/load requests picking different engines race: request A selects engine X, request B switches to engine Y (unloading idle X), then A calls begin_load_on(expected_engine=X, start=...) — the check sees Y active and raises. Also any code path that captures the engine, yields, then registers the load.

Common situations: Concurrent UI actions (a user flipping engine preference while a load starts); automation firing parallel load requests; GGUF-vs-diffusers selection flapping under concurrent traffic.

Related errors

• Could not switch the diffusion engine to {name}: unloading t
• A transformers installation is replacing the latest sidecar;
• A diffusion load is already in progress.
• Diffusion generation was cancelled.
• ChatGPT credential update is busy. Please retry.

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