unslothai/unsloth · warning · SidecarSwapInProgress

A transformers installation is replacing the latest sidecar;

Error message

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

What it means

SidecarSwapInProgress raised by the export orchestrator before spawning the export sidecar when utils.transformers_version reports a sidecar swap in progress: either a lazy REPAIR is actively rebuilding the sidecar, or an INSTALL reservation exists while no export is active. Spawning an export against a sidecar that is being replaced would pin or observe a half-swapped transformers installation, so the caller is told to retry after the swap completes.

Source

Thrown at studio/backend/core/export/orchestrator.py:225

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

    def _spawn_subprocess(self, config: dict) -> None:
        """Spawn a new export subprocess."""
        # Last-resort recheck for spawns outside an active op. Inside an op, _export_active is set and
        # load_checkpoint already rechecked, so a reservation here is an install about to observe
        # is_export_active() and abort; raising would kill this export for an install that never proceeds.
        from utils.transformers_version import sidecar_swap_in_progress

        from utils.transformers_version import sidecar_swap_kind

        _swap_kind = sidecar_swap_kind()
        # Inside an active op an INSTALL reservation is about to abort on the
        # is_export_active check, but a lazy REPAIR has no such check and can be
        # rebuilding the sidecar right now, so it must always refuse the spawn.
        if _swap_kind == "repair" or (_swap_kind is not None and not self._export_active):
            from utils.transformers_version import SidecarSwapInProgress
            raise SidecarSwapInProgress(
                "A transformers installation 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()

View on GitHub (pinned to 203007d190)

Solutions

Retry the export after the transformers install/repair completes (the error is deliberately transient).
Avoid initiating transformers version installs/switches while exports are queued or running.
Operators: if it persists, inspect sidecar_swap_kind()/the swap state to see whether a repair is stuck.
Surface the message to the user as 'retry shortly' rather than a hard failure.

Example fix

# before
result = orchestrator.run_export(cfg)

# after
for attempt in range(5):
    try:
        result = orchestrator.run_export(cfg)
        break
    except SidecarSwapInProgress:
        time.sleep(10)  # transformers install is replacing the sidecar; retry
else:
    raise RuntimeError('sidecar swap never completed')

Defensive patterns

Strategy: retry

Validate before calling

from utils.transformers_version import sidecar_swap_in_progress
if sidecar_swap_in_progress():
    wait_for_swap_to_finish()  # or defer the export

Try / catch

try:
    orchestrator.run_export(cfg)
except SidecarSwapInProgress:
    schedule_retry(delay=10)  # transient: transformers install is replacing the sidecar

Prevention

Do not start exports while transformers version installs/switches are in flight.
Classify SidecarSwapInProgress as retryable in orchestrating code and UIs.
Surface 'retry when it completes' messaging instead of a hard failure.

When it happens

Trigger: A transformers version install/repair starting concurrently with an export request (install about to observe is_export_active() and abort, but a repair has no such check); a lazy repair triggered by the version manager rebuilding the sidecar exactly when a new export spawns; frequent transformers version switching in the UI racing exports.

Common situations: Users switching transformers versions while queued exports fire; first export after an upgrade triggering a lazy sidecar repair; automation that installs transformers versions and exports in quick succession.

Related errors

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