unslothai/unsloth · error · HTTPException

Could not import '{entry['repo']}': {e}

Error message

Could not import '{entry['repo']}': {e}

What it means

HTTP 502 from the import route: the materialization step (_materialize_imagefolder_jsonl or _materialize_hf_dataset) raised a non-HTTP exception — a network failure, HF auth/availability error, JSONL parse error, disk error — which is wrapped into a readable message including the underlying exception text. The staging directory is cleaned up; nothing partial is promoted.

Source

Thrown at studio/backend/routes/training.py:4272

                folder.mkdir(parents = True, exist_ok = True)
                for moved, original in folded:
                    try:
                        if moved.exists() and not original.exists():
                            shutil.move(str(moved), str(original))
                    except OSError:
                        # Best effort: one unrestorable entry must not mask the original failure.
                        pass

            try:
                try:
                    if entry["loader"] == "imagefolder_jsonl":
                        imported = _materialize_imagefolder_jsonl(entry, staging, cap)
                    else:
                        imported = _materialize_hf_dataset(entry, staging, cap)
                except HTTPException:
                    raise
                except Exception as e:  # noqa: BLE001 -- surface a readable fetch/parse failure
                    raise HTTPException(
                        status_code = 502,
                        detail = f"Could not import '{entry['repo']}': {e}",
                    )
                if imported == 0:
                    raise HTTPException(
                        status_code = 502,
                        detail = f"No images found in '{entry['repo']}'.",
                    )
                # Promote the fully-materialized staging dir as a UNIT: a same-filesystem rename is atomic, so a hard process death
                # leaves either the old folder or the finished import. rmdir needs an empty target, so fold any pre-existing files (a .thumbs cache, an older metadata.jsonl) INTO staging first and keep one atomic promotion.
                try:
                    for p in sorted(folder.iterdir()):
                        # Same name in both: the imported file wins, as the previous per-file move did. Park the old one in the rescue dir so the folder can be emptied for the rename without destroying it.
                        dest = (rescue if (staging / p.name).exists() else staging) / p.name
                        shutil.move(str(p), str(dest))
                        folded.append((dest, p))
                    os.rmdir(folder)
                    os.replace(str(staging), str(folder))

View on GitHub (pinned to 203007d190)

Solutions

1. Read the embedded {e} — it names the real cause; fix that first (network, HF token via huggingface-cli login, disk space).
2. Retry the import after transient network/429 errors — materialization is fully re-started from staging, so retries are safe.
3. If the repo is gated or moved, pick another example or update Studio's curated list.

Example fix

# authenticate for gated HF repos before importing
huggingface-cli login
df -h /studio/datasets   # ensure staging space

import socket, urllib.request

def hf_reachable() -> bool:
    try:
        urllib.request.urlopen('https://huggingface.co', timeout=5)
        return True
    except OSError:
        return False

def is_import_wrapped_failure(exc: HTTPException) -> bool:
    return exc.status_code == 502 and str(exc.detail).startswith("Could not import")

for attempt in range(3):
    try:
        resp = await api.importExample(ex.id)
        break
    except HTTPStatusError as e:
        if e.response.status_code == 502 and 'Could not import' in e.response.text:
            await backoff(attempt)  # transient HF/network errors are common
            continue
        raise

When it happens

Trigger: Any unexpected exception while fetching/parsing the upstream dataset: Hugging Face connection reset or 429 rate limit, gated repo requiring a token, malformed metadata.jsonl in an imagefolder repo, or a local OSError while writing staging files. HTTPExceptions from deeper checks (e.g. 1354/1355) are re-raised untouched.

Common situations: Flaky network to huggingface.co; rate limiting during bulk imports; gated/private repos without configured credentials; upstream repo files renamed/removed; disk full while staging.

Related errors

• '{entry['repo']}' has no image column to import.
• No images found in '{entry['repo']}'.
• '{repo}' is gated on Hugging Face and this model cannot be d
• Download stalled for '{model_name}' even with HF_HUB_DISABLE
• Could not verify STT model '{model_id}'. Check that the repo

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