{"record":{"id":"48f6ee6aa56f693d","repo":"odysseus-dev/odysseus","slug":"huggingface-hub-is-required-to-download-mlx-image","errorCode":null,"errorMessage":"huggingface_hub is required to download MLX image model snapshots. Install the model requirements in the selected Python environment.","messagePattern":"huggingface_hub is required to download MLX image model snapshots\\. Install the model requirements in the selected Python environment\\.","errorType":"http","errorClass":"HTTPException","httpStatus":503,"severity":"error","filePath":"scripts/mlx_image_server.py","lineNumber":152,"sourceCode":"    )\n\n\ndef _resolve_bridge(names: list[str]) -> str:\n    for name in names:\n        found = _resolve_cli(name)\n        if found:\n            return found\n    return \"\"\n\n\ndef _snapshot_path(model: str) -> Path:\n    p = Path(model).expanduser()\n    if p.exists():\n        return p\n    try:\n        from huggingface_hub import snapshot_download\n    except Exception as e:\n        raise HTTPException(\n            503,\n            \"huggingface_hub is required to download MLX image model snapshots. \"\n            \"Install the model requirements in the selected Python environment.\",\n        ) from e\n    return Path(snapshot_download(model))\n\n\ndef _weights_path(model: str) -> Path:\n    p = Path(model).expanduser()\n    if p.is_file():\n        return p\n    snap = _snapshot_path(model)\n    if snap.is_file():\n        return snap\n    candidates = sorted(snap.rglob(\"*.safetensors\"))\n    if not candidates:\n        raise HTTPException(500, f\"No safetensors weights found for {model} in {snap}\")\n    return candidates[0]","sourceCodeStart":134,"sourceCodeEnd":170,"githubUrl":"https://github.com/odysseus-dev/odysseus/blob/f9235ebbf13f693a6fd29ce70b097f6ec83705bf/scripts/mlx_image_server.py#L134-L170","documentation":"Raised by _snapshot_path in scripts/mlx_image_server.py when the model string is not an existing local path and the optional huggingface_hub package cannot be imported in the server's Python environment. The server needs snapshot_download to fetch MLX image model weights from the Hub; without the dependency it returns HTTP 503 instead of an ImportError traceback.","triggerScenarios":"Requesting any MLX model by repo id (e.g. 'flux-1-schnell' or a HiDream/Boogu repo) when huggingface_hub is not installed in the Python that launched the server, and the model is not already a local directory.","commonSituations":"Server launched from a different virtualenv/conda env than the one where dependencies were installed; Apple Silicon MLX setup where only mflux was pip-installed; system python3 vs homebrew python mismatch; fresh checkout without running requirements install.","solutions":["Install huggingface_hub in the exact environment used to launch mlx_image_server.py (pip install -U huggingface_hub)","Verify with: <launch-python> -c 'import huggingface_hub' from the same interpreter","Alternatively pre-download the snapshot and pass a local absolute path as --model so snapshot_download is never needed"],"exampleFix":"# before\npython scripts/mlx_image_server.py --model black-forest-labs/FLUX.1-schnell\n# after\npip install -U huggingface_hub\npython scripts/mlx_image_server.py --model black-forest-labs/FLUX.1-schnell","handlingStrategy":"type-guard","validationCode":"import importlib.util, sys, subprocess\nspec = importlib.util.find_spec('huggingface_hub')\nif spec is None:\n    subprocess.check_call([sys.executable, '-m', 'pip', 'install', '-U', 'huggingface_hub'])","typeGuard":"def has_hf_hub() -> bool:\n    import importlib.util\n    return importlib.util.find_spec('huggingface_hub') is not None","tryCatchPattern":null,"preventionTips":["Preflight-import all optional deps in the launch interpreter before starting the server","Pin the launch command to one venv (uvicorn programmatically or a wrapper script)","Pre-download snapshots so runtime imports never need huggingface_hub"],"tags":["mlx","huggingface","dependency","http-503"],"backgroundTag":null,"analyzedSha":"f9235ebbf13f693a6fd29ce70b097f6ec83705bf","analyzedAt":"2026-08-14T21:47:48.359Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}