unslothai/unsloth · warning · HTTPException

dataset_local_cache_miss

dataset_local_cache_miss

Error message

Dataset is not available in the local cache.

What it means

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'.

Source

Thrown at studio/backend/hub/services/datasets/formatting.py:375

            train_split = request.train_split or "train"
            preview_slice, total_rows = _load_local_preview_slice(
                dataset_path = dataset_path,
                train_split = train_split,
                preview_size = PREVIEW_SIZE,
            )
        else:
            from datasets import Dataset, load_dataset

            # Tier 1: list_repo_files → load only the first data file
            cached_preview = (
                _load_any_cached_hf_preview_slice(request, PREVIEW_SIZE, hf_token)
                if request.prefer_local_cache
                else None
            )
            if cached_preview is not None:
                preview_slice, total_rows = cached_preview
            elif request.prefer_local_cache:
                raise HTTPException(
                    status_code = 404,
                    detail = {
                        "code": _LOCAL_CACHE_MISS_ERROR_CODE,
                        "message": "Dataset is not available in the local cache.",
                    },
                )
            else:
                preview_slice = None

                try:
                    from huggingface_hub import HfApi

                    api = HfApi()
                    repo_files = api.list_repo_files(
                        request.dataset_name,
                        repo_type = "dataset",
                        token = hf_token or None,
                    )

View on GitHub (pinned to 203007d190)

Solutions

1. Download the dataset first (start-dataset-download endpoint) and wait for completion, then retry the preview.
2. Retry without prefer_local_cache (or with it false) when network access is available, letting Tier-1 remote preview run.
3. Check the cache inventory endpoint to confirm the repo actually has a complete local snapshot.
4. Handle the structured code `dataset_local_cache_miss` in the client to show a 'Download first' prompt instead of a generic error.

Example fix

# before
preview = await client.preview(req)  # raises 404
# after
if not await client.is_cached(req.dataset_name):
    await client.start_download(req.dataset_name)
    await client.wait_download(req.dataset_name)
preview = await client.preview(req)

inv = get_cache_inventory(client)
cached = {e.repo_id.lower(): e for e in inv.entries if e.complete}
req.prefer_local_cache = req.dataset_name.lower() in cached  # only ask for local when it can succeed

try:
    preview = get_preview(client, req)
except HTTPStatusError as e:
    if e.response.status_code == 404 and e.response.json()["detail"].get("code") == "dataset_local_cache_miss":
        prompt_user_to_download(req.dataset_name)
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• STT model '{model_id}' is not downloaded. Download it in Set
• Dataset not found in cache
• This dataset is no longer on disk. Add it again or pick anot
• Dataset appears to be empty or could not be streamed
• Selected cached model is no longer available.

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