unslothai/unsloth · error · HTTPException

Failed to export GGUF model

Error message

Failed to export GGUF model

What it means

Generic 500 from the GGUF export endpoint's catch-all: an exception escaped backend.export_gguf (which normally returns failure tuples rather than raising) or the post-export _export_details call. HTTPExceptions pass through and SidecarSwapInProgress becomes a 409, so this 500 marks an unexpected crash; the real traceback is in the server log under 'Error exporting GGUF model:'.

Source

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

        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 GGUF model: {e}", exc_info = True)
        raise HTTPException(
            status_code = 500,
            detail = "Failed to export GGUF model",
        )


@router.post("/export/lora", response_model = ExportOperationResponse)
async def export_lora_adapter(
    request: ExportLoRAAdapterRequest, current_subject: str = Depends(get_current_subject)
):
    """Export only the LoRA adapter (if the loaded model is PEFT).

    Wraps ExportBackend.export_lora_adapter.
    """
    try:
        await _ensure_export_supported()
        backend = get_export_backend()
        success, message, output_path = await asyncio.to_thread(
            backend.export_lora_adapter,

View on GitHub (pinned to 203007d190)

Solutions

1. Check the backend log traceback for the exact exception; the HTTP detail is intentionally uninformative.
2. If OOM: free GPU/RAM, close other jobs, or choose a smaller quantization method.
3. Confirm gguf conversion dependencies are installed and the save volume has space for the full output.
4. If push_to_hub was set, verify hf_token is valid and repo_id is writable, or retry without pushing.

Example fix

# before
resp = client.post('/api/export/gguf', json={'push_to_hub': True, 'repo_id': 'me/model'})
# 500 'Failed to export GGUF model'

# after
resp = client.post('/api/export/gguf', json={'push_to_hub': False})  # export locally first
# then push separately once the local artifact is confirmed good

// preflight: free memory and disk before large quantizations
const mem = await getGpuMemory(); if (mem.freeMb < neededMb) throw new Error('Not enough memory to quantize');

try { await exportGguf(body); }
catch (e) { if (e.status === 500) { await fetchBackendLogTail(); throw new ExportFailedWithLog(); } }

When it happens

Trigger: POST /export/gguf where the conversion subprocess dies unexpectedly (OOM during quantization, missing llama.cpp/conversion dependency, disk full mid-write), or _export_details failing on the produced output path.

Common situations: Large models quantized on memory-constrained hosts (OOM killer), missing gguf conversion tooling in the environment, disk exhaustion during a multi-format export, or push_to_hub with an invalid/revoked hf_token raising from the hub client.

Related errors

• GGUF conversion produced a symlink, refusing to relocate it:
• GGUF conversion produced no files: no .gguf outputs for {abs
• GGUF conversion produced a symlinked Modelfile, refusing to
• Failed to send command to subprocess: {exc}
• Export subprocess crashed during wait

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