What causes "Failed to load checkpoint" in unslothai/unsloth?

Inspect the backend log for the 'Error loading checkpoint' entry — the traceback identifies the true cause.

unslothai/unsloth · error · HTTPException

Failed to load checkpoint

Error message

Failed to load checkpoint

What it means

Catch-all HTTP 500 for load_checkpoint: any exception that is not an HTTPException and not SidecarSwapInProgress is logged (with traceback) and masked as 'Failed to load checkpoint'. The real cause is only visible in server logs via logger.error(..., exc_info=True).

Source

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

            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

Inspect the backend log for the 'Error loading checkpoint' entry — the traceback identifies the true cause.
Free VRAM/RAM (run /export/cleanup, close other model processes) and retry with a smaller model or load_in_4bit=True.
Re-download or re-export the checkpoint if the traceback shows weight-file corruption.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await api.post('/export/load-checkpoint', body);
} catch (e) {
  if (e.status === 500) captureServerLogContext('Error loading checkpoint');
  throw e;
}

Prevention

Always pair client 500s with a server-log lookup — the real traceback is only there.
Free GPU memory and verify checkpoint integrity before retrying.

When it happens

Trigger: Unexpected backend failures: OOM during model load, corrupted safetensors, a bug inside ExportBackend.load_checkpoint, or filesystem permission errors on the checkpoint directory.

Common situations: CUDA out-of-memory on large checkpoints; partially downloaded/corrupt weights; disk full; version skew between installed transformers and the checkpoint format.

Related errors

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