unslothai/unsloth · error · HTTPException

{unavailable_reason}

Error message

{unavailable_reason}

What it means

HTTP 400 from resolve_transport when the requested transport (xet or http) is unavailable in this environment — `download_registry.download_transport_unavailable_reason` returned a reason string, which is surfaced verbatim as the detail. It fires before any worker spawns, so nothing is downloaded and no job is registered. Commonly the xet extra/CLI is missing, or the environment explicitly disabled xet.

Source

Thrown at studio/backend/hub/services/download_lifecycle.py:99

        return (True, "Xet")
    return (bool(health.use_xet), str(health.reason))


def _allow_high_performance() -> bool:
    """Legacy opt-in, still honoured for installs whose unsloth_zoo cannot size the worker itself."""
    return os.environ.get("UNSLOTH_XET_ALLOW_HIGH_PERFORMANCE", "").strip().lower() in (
        "1",
        "true",
        "yes",
        "on",
    )


def resolve_transport(use_xet: bool) -> str:
    transport = download_registry.TRANSPORT_XET if use_xet else download_registry.TRANSPORT_HTTP
    unavailable_reason = download_registry.download_transport_unavailable_reason(transport)
    if unavailable_reason is not None:
        raise HTTPException(status_code = 400, detail = unavailable_reason)
    return transport


def write_files_manifest(files: Sequence[str]) -> str:
    """Stage a scoped job's file list in a temp JSON file and return its path.

    The worker deletes it after reading. A pipeline repo lists hundreds of files, well past
    what is comfortable on a command line."""
    import json
    import tempfile

    handle = tempfile.NamedTemporaryFile(
        mode = "w", suffix = ".json", prefix = "unsloth-dl-files-", delete = False, encoding = "utf-8"
    )
    with handle:
        json.dump(list(files), handle)
    return handle.name

View on GitHub (pinned to 203007d190)

Solutions

1. Read the returned reason string — it states exactly which capability is missing.
2. Install/enable the xet support in the backend environment (pip extra or bundled binary), or set the env flag that permits it.
3. Switch the request to the http transport (transport_mode) to proceed immediately without xet.
4. Redeploy the same dependency set across environments so saved transport preferences stay valid.

Example fix

# before
DownloadDatasetRequest(repo_id="squad", transport_mode="xet")  # xet not installed -> 400
# after
DownloadDatasetRequest(repo_id="squad", transport_mode="http")

reason = download_transport_unavailable_reason("xet")  # same check the server runs
transport = None if reason else "xet"   # probe before requesting
body = DownloadDatasetRequest(repo_id=rid, transport_mode=transport or "http")

def transport_available(mode: str) -> TypeGuard[str]:
    return mode in ("xet", "http") and download_transport_unavailable_reason(mode) is None

try:
    start_download(client, DownloadDatasetRequest(repo_id=rid, transport_mode="xet"))
except HTTPStatusError as e:
    if e.response.status_code == 400:  # detail is the unavailability reason
        start_download(client, DownloadDatasetRequest(repo_id=rid, transport_mode="http"))
    else:
        raise

When it happens

Trigger: Requesting transport_mode="xet" (or auto-resolving to xet) when the xet package/binary is not installed in the backend environment; requesting a transport the registry has marked unavailable via env flags (e.g. high-performance Xet not enabled where required).

Common situations: Studio installed without the [xet] extra; a slim Docker image missing the xet CLI; transport pinned to xet in saved user settings after moving to an environment without it; HTTP transport disabled by policy.

Related errors

• Download stalled for '{model_name}' even with HF_HUB_DISABLE
• Failed to start {log_prefix.lower()}: {scrubbed}
• {exc}
• GPU selection is unavailable on this host: {exc}
• Requested GPU {wanted} but none of them are visible to this

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