unslothai/unsloth · warning · SidecarSwapInProgress

A transformers repair is replacing the latest sidecar; retry

Error message

A transformers repair is replacing the latest sidecar; retry when it completes.

What it means

Raised at model-load time when sidecar_swap_kind() reports 'repair': a transformers version repair is currently replacing the latest inference sidecar binary. Loads are aborted (not queued) during a repair because the repair swaps files without holding the lifecycle gate the loader owns; the caller should retry once the repair finishes.

Source

Thrown at studio/backend/core/inference/orchestrator.py:358

    # ------------------------------------------------------------------
    # Subprocess lifecycle
    # ------------------------------------------------------------------

    def _spawn_subprocess(self, config: dict) -> None:
        """Spawn a new inference subprocess."""
        # Same recheck as the training/export spawns, REPAIR reservations only: a
        # repair swaps without holding the lifecycle gate this load's caller owns,
        # while an install cannot swap until this gate is released (and then its
        # queued-load snapshot aborts it), so tolerating installs here lets the
        # load win instead of failing both sides. Also covers the OpenAI
        # auto-switch path, which enters _load_model_impl without route guards.
        from utils.transformers_version import (
            SidecarSwapInProgress,
            sidecar_swap_kind,
        )

        if sidecar_swap_kind() == "repair":
            raise SidecarSwapInProgress(
                "A transformers repair is replacing the latest sidecar; retry when it completes."
            )
        from utils.native_path_leases import (
            native_path_secret_removed_for_child_start,
            run_without_native_path_secret,
        )
        from utils.hf_cache_settings import child_environment_for_spawn, get_hf_cache_paths

        cache_env = get_hf_cache_paths().child_env({})

        with (
            child_environment_for_spawn(cache_env),
            native_path_secret_removed_for_child_start(),
        ):
            self._cmd_queue = _CTX.Queue()
            self._resp_queue = _CTX.Queue()
            self._cancel_event = _CTX.Event()
            self._drain_event = _CTX.Event()

View on GitHub (pinned to 203007d190)

Solutions

Catch SidecarSwapInProgress and retry the load after the repair completes (poll sidecar_swap_kind() or subscribe to repair completion)
Surface 'repairing transformers runtime, retry shortly' in the UI instead of a hard failure
Avoid scheduling loads while repair jobs are known to run

Example fix

# before
await orchestrator.load_model(model_id)  # raises SidecarSwapInProgress once

# after
for _ in range(30):
    try:
        await orchestrator.load_model(model_id)
        break
    except SidecarSwapInProgress:
        await asyncio.sleep(2)  # repair still swapping; retry

Defensive patterns

Strategy: retry

Validate before calling

from utils.transformers_version import sidecar_swap_kind

if sidecar_swap_kind() == 'repair':
    wait_for_sidecar_repair_completion()  # poll or subscribe before loading

Try / catch

from utils.transformers_version import SidecarSwapInProgress

for _ in range(MAX_WAIT_SLOTS):
    try:
        await orchestrator.load_model(model_id)
        break
    except SidecarSwapInProgress:
        await asyncio.sleep(2)

Prevention

Disable or queue load buttons while a repair job is known to run
Treat SidecarSwapInProgress as retryable by classification, not by string matching
Make repair completion observable so callers can await it instead of polling

When it happens

Trigger: Calling the model-load path (_load_model_impl, including the OpenAI auto-switch route) exactly while a transformers version repair job is swapping the sidecar. The check deliberately tolerates installs (which queue) but not repairs.

Common situations: Model load request arriving right as an automated repair (e.g. after a corrupted/failed transformers install) starts; UI 'Load model' clicked during a background version fix; auto-switch to OpenAI racing a repair.

Related errors

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