{"record":{"id":"2dc99d1dc2f426d7","repo":"unslothai/unsloth","slug":"dataset-local-cache-miss","errorCode":"dataset_local_cache_miss","errorMessage":"Dataset is not available in the local cache.","messagePattern":"Dataset is not available in the local cache\\.","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"warning","filePath":"studio/backend/hub/services/datasets/formatting.py","lineNumber":375,"sourceCode":"            train_split = request.train_split or \"train\"\n            preview_slice, total_rows = _load_local_preview_slice(\n                dataset_path = dataset_path,\n                train_split = train_split,\n                preview_size = PREVIEW_SIZE,\n            )\n        else:\n            from datasets import Dataset, load_dataset\n\n            # Tier 1: list_repo_files → load only the first data file\n            cached_preview = (\n                _load_any_cached_hf_preview_slice(request, PREVIEW_SIZE, hf_token)\n                if request.prefer_local_cache\n                else None\n            )\n            if cached_preview is not None:\n                preview_slice, total_rows = cached_preview\n            elif request.prefer_local_cache:\n                raise HTTPException(\n                    status_code = 404,\n                    detail = {\n                        \"code\": _LOCAL_CACHE_MISS_ERROR_CODE,\n                        \"message\": \"Dataset is not available in the local cache.\",\n                    },\n                )\n            else:\n                preview_slice = None\n\n                try:\n                    from huggingface_hub import HfApi\n\n                    api = HfApi()\n                    repo_files = api.list_repo_files(\n                        request.dataset_name,\n                        repo_type = \"dataset\",\n                        token = hf_token or None,\n                    )","sourceCodeStart":357,"sourceCodeEnd":393,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/hub/services/datasets/formatting.py#L357-L393","documentation":"HTTP 404 with machine-readable code `dataset_local_cache_miss`, raised when the preview request set prefer_local_cache=true (offline/local-only mode) and no cached HF preview slice could be loaded for the dataset. The structured detail ({code, message}) exists so clients can distinguish 'not cached locally' from 'dataset does not exist'.","triggerScenarios":"Requesting a preview with prefer_local_cache=true for a hub dataset that was never downloaded, whose download is still in progress, or whose cache snapshot does not contain a loadable preview file.","commonSituations":"Offline/air-gapped Studio deployments; user switched to local-cache mode before the download finished; cache was pruned; the dataset only has file formats the local preview loader cannot read.","solutions":["Download the dataset first (start-dataset-download endpoint) and wait for completion, then retry the preview.","Retry without prefer_local_cache (or with it false) when network access is available, letting Tier-1 remote preview run.","Check the cache inventory endpoint to confirm the repo actually has a complete local snapshot.","Handle the structured code `dataset_local_cache_miss` in the client to show a 'Download first' prompt instead of a generic error."],"exampleFix":"# before\npreview = await client.preview(req)  # raises 404\n# after\nif not await client.is_cached(req.dataset_name):\n    await client.start_download(req.dataset_name)\n    await client.wait_download(req.dataset_name)\npreview = await client.preview(req)","handlingStrategy":"validation","validationCode":"inv = get_cache_inventory(client)\ncached = {e.repo_id.lower(): e for e in inv.entries if e.complete}\nreq.prefer_local_cache = req.dataset_name.lower() in cached  # only ask for local when it can succeed","typeGuard":null,"tryCatchPattern":"try:\n    preview = get_preview(client, req)\nexcept HTTPStatusError as e:\n    if e.response.status_code == 404 and e.response.json()[\"detail\"].get(\"code\") == \"dataset_local_cache_miss\":\n        prompt_user_to_download(req.dataset_name)\n    else:\n        raise","preventionTips":["Check the structured detail.code field — it exists precisely to disambiguate this case.","Gate offline mode on cache-completeness from the inventory endpoint.","After starting a download, wait for the job's terminal state before retrying local-only previews."],"tags":["cache","offline","huggingface","http-404","preview"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}