unslothai/unsloth · warning · HTTPException

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

HTTP 409 raised when load_checkpoint loses the race against a sidecar install: the generic exception handler catches SidecarSwapInProgress from utils.transformers_version and converts it into a retryable conflict. Unlike the up-front 409 (error 1065), this one fires when the swap starts after the request passed the pre-check — the worker hit the half-replaced .venv_t5_latest mid-flight.

Source

Thrown at studio/backend/routes/export.py:115

            load_in_4bit = request.load_in_4bit,
            trust_remote_code = request.trust_remote_code,
            approved_remote_code_fingerprint = request.approved_remote_code_fingerprint,
            hf_token = request.hf_token,
            subject = current_subject,
        )

        if not success:
            raise HTTPException(status_code = 400, detail = message)

        return ExportOperationResponse(success = True, message = message)
    except HTTPException:
        raise
    except Exception as e:
        from utils.transformers_version import SidecarSwapInProgress

        if isinstance(e, SidecarSwapInProgress):
            # Expected loss of the race against a sidecar install: retryable 409.
            raise HTTPException(status_code = 409, detail = str(e))
        logger.error(f"Error loading checkpoint: {e}", exc_info = True)
        raise HTTPException(
            status_code = 500,
            detail = "Failed to load checkpoint",
        )


@router.post("/cleanup", response_model = ExportOperationResponse)
async def cleanup_export_memory(current_subject: str = Depends(get_current_subject)):
    """Cleanup export-related models from memory (ExportBackend.cleanup_memory)."""
    try:
        backend = get_export_backend()
        success = await asyncio.to_thread(backend.cleanup_memory)

        if not success:
            raise HTTPException(
                status_code = 500,
                detail = "Memory cleanup failed. See server logs for details.",

View on GitHub (pinned to 203007d190)

Solutions

Retry the request after the install completes — this 409 is explicitly documented as expected and retryable.
Add a client-side check on install status before retrying so you do not hammer the endpoint mid-install.
Operationally, avoid starting installs while exports are queued.

Defensive patterns

Strategy: retry

Try / catch

try {
  await api.post('/export/load-checkpoint', body);
} catch (e) {
  if (e.status === 409 && /replacing the latest sidecar/.test(e.detail)) {
    await waitForInstallCompletion(); return retry();
  }
  throw e;
}

Prevention

Distinguish the two 409s: pre-check (1065) vs mid-flight sidecar swap (1068) — both retry after install completes.
Serialize installs and exports operationally so this race cannot occur.

When it happens

Trigger: A transformers install begins between _ensure_export_supported() passing and backend.load_checkpoint touching the sidecar; the loader then observes the venv being renamed/replaced and raises SidecarSwapInProgress.

Common situations: Two operators (or a UI plus a script) using the system at once; an install triggered automatically right as a queued export starts; CI pipelines that upgrade and export concurrently.

Related errors

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