jamiepine/voicebox · error · HTTPException

Current model cache directory not found

Error message

Current model cache directory not found

What it means

404 from POST /models/migrate. The endpoint reads HF_HUB_CACHE from huggingface_hub.constants and checks source.exists(); if the configured cache directory does not exist on disk, it raises HTTPException(404, 'Current model cache directory not found'). This typically means HF_HOME/HF_HUB_CACHE points at a path that was never created, was deleted, or lives on an unmounted volume.

Source

Thrown at backend/routes/models.py:130

@router.get("/models/cache-dir")
async def get_models_cache_dir():
    """Get the path to the HuggingFace model cache directory."""
    from huggingface_hub import constants as hf_constants

    return {"path": str(Path(hf_constants.HF_HUB_CACHE))}


@router.post("/models/migrate")
async def migrate_models(request: models.ModelMigrateRequest):
    """Move all downloaded models to a new directory with byte-level progress via SSE."""
    from huggingface_hub import constants as hf_constants

    source = Path(hf_constants.HF_HUB_CACHE)
    destination = Path(request.destination)

    if not source.exists():
        raise HTTPException(status_code=404, detail="Current model cache directory not found")

    if source.resolve() == destination.resolve():
        raise HTTPException(status_code=400, detail="Source and destination are the same directory")

    if destination.resolve().is_relative_to(source.resolve()):
        raise HTTPException(status_code=400, detail="Destination cannot be inside the current cache directory")

    progress_manager = get_progress_manager()
    model_dirs = [d for d in source.iterdir() if d.name.startswith("models--") and d.is_dir()]
    if not model_dirs:
        progress_manager.update_progress("migration", 1, 1, status="complete")
        progress_manager.mark_complete("migration")
        return {"moved": 0, "errors": [], "source": str(source), "destination": str(destination)}

    destination.mkdir(parents=True, exist_ok=True)

    same_fs = False
    try:

View on GitHub (pinned to 51f49dea19)

Solutions

1. Run GET /models/cache-dir to see which path the server treats as source, then confirm that directory exists on the host.
2. If the cache is legitimately empty, create the directory (mkdir -p) or download a model first so HuggingFace creates it.
3. Correct the HF_HOME / HF_HUB_CACHE env var to point at the real cache location and restart the backend.
4. If a volume should be mounted there, remount it before retrying migrate.

Example fix

# before — HF_HUB_CACHE points at unmounted path
GET /models/cache-dir  -> {"path": "/mnt/models"}  # absent
# after
mkdir -p /mnt/models && export HF_HOME=/mnt/models  # then restart backend

async function preflightMigrate(dest: string) {
  const { path: cacheDir } = await (await fetch('/models/cache-dir')).json();
  const exists = await checkDirExists(cacheDir); // platform helper or a HEAD on a fs API
  if (!exists) throw new Error(`Cache directory ${cacheDir} does not exist; set HF_HOME correctly or download a model first.`);
  return await fetch('/models/migrate', {method:'POST', body: JSON.stringify({destination: dest})});
}

try {
  await fetch('/models/migrate', {method:'POST', body: JSON.stringify({destination})});
} catch (e) {
  if (e.response?.status === 404 && /cache directory not found/i.test(e.response.detail)) {
    // prompt user to fix HF_HOME / mount the volume, then retry
  } else throw e;
}

When it happens

Trigger: POST /models/migrate with any destination body when HF_HUB_CACHE resolves to a non-existent path (e.g. /mnt/models that isn't mounted, or a custom HF_HOME whose cache subdir was never populated).

Common situations: Custom HF_HOME/HF_HUB_CACHE env var set but directory not yet created; first run before any model downloaded; cache moved/deleted out of band; container started without the model volume mounted; fresh install where HF_HOME points to a removable drive that's ejected.

Related errors

• Source and destination are the same directory
• Destination cannot be inside the current cache directory
• Model {model_name} not found in cache
• Failed to delete model cache directory: {str(e)}
• Failed to resolve save path from dialog

AI-assisted analysis of jamiepine/voicebox@51f49dea19 (2026-08-12). Data as JSON: /api/errors/ed369ffe01bb75f2. Report an issue: GitHub.