{"record":{"id":"3e0a5c25e9dfa15f","repo":"unslothai/unsloth","slug":"unavailable-reason","errorCode":null,"errorMessage":"{unavailable_reason}","messagePattern":"\\{unavailable_reason\\}","errorType":"http","errorClass":"HTTPException","httpStatus":400,"severity":"error","filePath":"studio/backend/hub/services/download_lifecycle.py","lineNumber":99,"sourceCode":"        return (True, \"Xet\")\n    return (bool(health.use_xet), str(health.reason))\n\n\ndef _allow_high_performance() -> bool:\n    \"\"\"Legacy opt-in, still honoured for installs whose unsloth_zoo cannot size the worker itself.\"\"\"\n    return os.environ.get(\"UNSLOTH_XET_ALLOW_HIGH_PERFORMANCE\", \"\").strip().lower() in (\n        \"1\",\n        \"true\",\n        \"yes\",\n        \"on\",\n    )\n\n\ndef resolve_transport(use_xet: bool) -> str:\n    transport = download_registry.TRANSPORT_XET if use_xet else download_registry.TRANSPORT_HTTP\n    unavailable_reason = download_registry.download_transport_unavailable_reason(transport)\n    if unavailable_reason is not None:\n        raise HTTPException(status_code = 400, detail = unavailable_reason)\n    return transport\n\n\ndef write_files_manifest(files: Sequence[str]) -> str:\n    \"\"\"Stage a scoped job's file list in a temp JSON file and return its path.\n\n    The worker deletes it after reading. A pipeline repo lists hundreds of files, well past\n    what is comfortable on a command line.\"\"\"\n    import json\n    import tempfile\n\n    handle = tempfile.NamedTemporaryFile(\n        mode = \"w\", suffix = \".json\", prefix = \"unsloth-dl-files-\", delete = False, encoding = \"utf-8\"\n    )\n    with handle:\n        json.dump(list(files), handle)\n    return handle.name\n","sourceCodeStart":81,"sourceCodeEnd":117,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/hub/services/download_lifecycle.py#L81-L117","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Read the returned reason string — it states exactly which capability is missing.","Install/enable the xet support in the backend environment (pip extra or bundled binary), or set the env flag that permits it.","Switch the request to the http transport (transport_mode) to proceed immediately without xet.","Redeploy the same dependency set across environments so saved transport preferences stay valid."],"exampleFix":"# before\nDownloadDatasetRequest(repo_id=\"squad\", transport_mode=\"xet\")  # xet not installed -> 400\n# after\nDownloadDatasetRequest(repo_id=\"squad\", transport_mode=\"http\")","handlingStrategy":"fallback","validationCode":"reason = download_transport_unavailable_reason(\"xet\")  # same check the server runs\ntransport = None if reason else \"xet\"   # probe before requesting\nbody = DownloadDatasetRequest(repo_id=rid, transport_mode=transport or \"http\")","typeGuard":"def transport_available(mode: str) -> TypeGuard[str]:\n    return mode in (\"xet\", \"http\") and download_transport_unavailable_reason(mode) is None","tryCatchPattern":"try:\n    start_download(client, DownloadDatasetRequest(repo_id=rid, transport_mode=\"xet\"))\nexcept HTTPStatusError as e:\n    if e.response.status_code == 400:  # detail is the unavailability reason\n        start_download(client, DownloadDatasetRequest(repo_id=rid, transport_mode=\"http\"))\n    else:\n        raise","preventionTips":["Install the xet extra/binary in every environment that will request xet transport.","Let clients fall back to http automatically when the 400 carries an unavailability reason.","Do not persist a transport preference that the current environment cannot honor."],"tags":["transport","xet","environment","http-400","download"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}