unslothai/unsloth · error · HTTPException

Failed to export base model

Error message

Failed to export base model

What it means

Generic 500 raised by the POST base-model export endpoint when the backend export call throws an unexpected exception. The handler first re-raises HTTPExceptions as-is and converts SidecarSwapInProgress into a 409, so this 500 means a genuinely unhandled failure inside ExportBackend's base export (run in a worker thread). The original exception is logged server-side with a full traceback via logger.error(..., exc_info=True).

Source

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

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

        return ExportOperationResponse(
            success = True,
            message = message,
            details = await asyncio.to_thread(_export_details, output_path, refresh_index = True),
        )
    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 exporting base model: {e}", exc_info = True)
        raise HTTPException(
            status_code = 500,
            detail = "Failed to export base model",
        )


@router.post("/export/gguf", response_model = ExportOperationResponse)
async def export_gguf(
    request: ExportGGUFRequest, current_subject: str = Depends(get_current_subject)
):
    """Export the current model to GGUF format, optionally pushing to Hub.

    Wraps ExportBackend.export_gguf.
    """
    try:
        await _ensure_export_supported()
        backend = get_export_backend()
        # A custom path wins; otherwise the imatrix toggle requests the upstream auto-download.
        imatrix_file = request.imatrix_path or (True if request.imatrix else None)

View on GitHub (pinned to 203007d190)

Solutions

1. Read the backend log for the 'Error exporting base model:' line — the exc_info traceback names the real cause; fix that first.
2. Confirm a model is actually loaded (check the trainer/model state endpoint) before issuing the export.
3. Verify the target save_directory exists and is writable and has free disk space.
4. If the log shows SidecarSwapInProgress but you still got a 500, check for a stale sidecar install and let it finish, then retry.
5. Reproduce with the same parameters from a notebook/script to surface the underlying traceback directly.

Example fix

// before
const r = await fetch('/api/export/base', {method:'POST', body: JSON.stringify({save_directory: '/out'})});
if (!r.ok) console.error(await r.text()); // opaque 'Failed to export base model'

// after
const r = await fetch('/api/export/base', {method:'POST', body: JSON.stringify({save_directory: '/out'})});
if (r.status === 500) {
  // server log carries the traceback; surface actionable context to the user
  throw new Error('Export failed — check backend log and that a model is loaded');
}

const state = await api.get('/api/trainer/state').then(r => r.json());
if (!state.model_loaded) throw new Error('Load a model before exporting');

try {
  const r = await api.post('/api/export/base', body);
} catch (e) {
  if (e.status === 500) { /* read backend log; show 'export failed, see server log' */ }
  else throw e;
}

When it happens

Trigger: POST to the base-model export route while no model is loaded in the trainer, when the save directory is unwritable or full, when the underlying transformers/unsloth export crashes (OOM, corrupt checkpoint, incompatible model class), or when _export_details fails after a successful export.

Common situations: Exporting right after a crashed training run, exporting a model that was swapped/unloaded by another request, disk exhaustion in the output directory, or a version-mismatched transformers install breaking the export path.

Related errors

• {message}
• Failed to load checkpoint
• Memory cleanup failed. See server logs for details.
• Failed to cleanup export memory
• Failed to cancel export

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