{
  "$type": "site.standard.document",
  "bskyPostRef": {
    "cid": "bafyreiexjyamhde5hhrwbuwsxqvwfr55g4rambgpfpv6rlbcrkypaptwra",
    "uri": "at://did:plc:pgryn3ephfd2xgft23qokfzt/app.bsky.feed.post/3mkqphxio5h32"
  },
  "path": "/t/runtime-errror/175679#post_2",
  "publishedAt": "2026-04-30T22:46:28.000Z",
  "site": "https://discuss.huggingface.co",
  "tags": [
    "Hugging Face Hub v1.0 migration guide",
    "Gradio changelog",
    "Hugging Face Spaces configuration reference",
    "Handling Spaces dependencies",
    "Spaces ZeroGPU documentation",
    "Gradio 5.7.1 changelog entry: “Use get_token instead of HfFolder.get_token”",
    "Example public issue: huggingface_hub 1.0.x removed HfFolder",
    "Example public issue: existing evaluate release broke after huggingface_hub 1.0.0",
    "Spaces configuration reference",
    "Spaces dependency docs",
    "Hugging Face Hub migration guide",
    "oobabooga issue explaining the same HfFolder failure",
    "Hugging Face evaluate issue after huggingface_hub 1.0.0",
    "Manage Spaces with huggingface_hub",
    "Spaces Overview",
    "Spaces GPU documentation",
    "ZeroGPU docs",
    "PyTorch local installation guide",
    "PyTorch install selector",
    "Hugging Face Hub download guide",
    "environment variable docs",
    "Download files from the Hub",
    "HF Hub environment variables: HF_HUB_OFFLINE",
    "Transformers offline-mode notes",
    "ZeroGPU documentation",
    "Diffusers memory optimization guide",
    "Gradio LoginButton docs",
    "@spaces.GPU"
  ],
  "textContent": "It’s a version compatibility issue. To give a familiar example, it’s similar to a situation where “a specific piece of software stopped working after installing Windows Update” in a broad sense.\n\n> Or do I need to wait for it to fix itself?\n\nYeah. Basically this. Or if you’re comfortable with coding:\n\n  * Fix the code in the Space yourself and use it as a Zero GPU Space for Pro subscribers, or use it locally (however, if it’s designed for Zero GPU Space like that particular Space, some porting work will be required for local use)\n  * Report the issue to the creator via the “Discussion” section in the Community tab of the problematic Space. Depending on the creator, this may speed up the fix\n  * Find another similar Space that works properly\n  * and so on…\n\n\n\n* * *\n\n# Runtime error on `AP123/IllusionDiffusion`: what it means, likely cause, and practical fixes\n\nThe error is meaningful, and it points to a fairly specific kind of breakage.\n\nThe important part of the traceback is this:\n\n\n    from huggingface_hub import HfFolder, whoami\n    ImportError: cannot import name 'HfFolder' from 'huggingface_hub'\n\n\nIn plain terms:\n\n**The app is crashing while importing Gradio, before the actual image-generation code runs.**\n\nSo this is probably **not** caused by:\n\n  * a bad prompt,\n  * a bad input image,\n  * a browser problem,\n  * a Stable Diffusion model problem,\n  * a ControlNet problem,\n  * a QR-code / illusion-image logic problem,\n  * or a normal GPU out-of-memory error.\n\n\n\nThe crash happens earlier. Python starts loading the app, imports Hugging Face ZeroGPU support, that imports Gradio, Gradio imports its OAuth code, and then Gradio tries to import `HfFolder` from `huggingface_hub`. In the installed version of `huggingface_hub`, `HfFolder` is no longer available.\n\nUseful references:\n\n  * Hugging Face Hub v1.0 migration guide\n  * Gradio changelog\n  * Hugging Face Spaces configuration reference\n  * Handling Spaces dependencies\n  * Spaces ZeroGPU documentation\n\n\n\n* * *\n\n## Short diagnosis\n\nThe likely cause is:\n\n\n    old Gradio\n    +\n    new huggingface_hub\n    =\n    ImportError: cannot import name 'HfFolder'\n\n\nMore specifically, the app appears to use an older Gradio runtime while allowing `huggingface_hub` to be installed without a safe upper version limit.\n\nOlder Gradio code expected this to work:\n\n\n    from huggingface_hub import HfFolder, whoami\n\n\nBut newer `huggingface_hub` versions removed the old `HfFolder` API. Hugging Face’s v1.0 migration guide explains that several deprecated APIs were removed in v1.0, and Gradio later fixed this class of issue by switching from `HfFolder.get_token()` to `get_token()` in Gradio 5.7.1.\n\nRelevant references:\n\n  * Hugging Face Hub v1.0 migration guide\n  * Gradio 5.7.1 changelog entry: “Use get_token instead of HfFolder.get_token”\n  * Example public issue: huggingface_hub 1.0.x removed HfFolder\n  * Example public issue: existing evaluate release broke after huggingface_hub 1.0.0\n\n\n\n* * *\n\n## Why this can happen suddenly\n\nA Hugging Face Space is not just the visible Python code. It is a combination of:\n\n  * the Space source files,\n  * the YAML block at the top of `README.md`,\n  * the selected SDK,\n  * the selected Gradio version,\n  * the Python version,\n  * `requirements.txt`,\n  * the current package resolver result,\n  * the Hugging Face runtime image,\n  * the selected hardware,\n  * cache state,\n  * and, for ZeroGPU Spaces, the `spaces` / `@spaces.GPU` runtime behavior.\n\n\n\nThe Spaces configuration reference says Spaces are configured through the YAML block at the top of `README.md`, and that `sdk_version` specifies the Gradio version. The Spaces dependency docs say extra Python packages are installed from `requirements.txt`.\n\nThat means a Space can have an older Gradio version pinned in `README.md`, while `huggingface_hub` is left unpinned in `requirements.txt`.\n\nA typical failure chain looks like this:\n\n\n    1. The Space rebuilds or restarts from a clean environment.\n    2. The Space keeps using an older Gradio version.\n    3. `huggingface_hub` is not pinned below 1.0.\n    4. The package installer resolves a newer `huggingface_hub`.\n    5. Old Gradio imports `HfFolder`.\n    6. New `huggingface_hub` does not provide `HfFolder`.\n    7. The app exits before the image-generation pipeline starts.\n\n\nThis also explains why several similar tools can fail around the same time. Many older Spaces were written against older dependency behavior but rebuild against newer packages.\n\n* * *\n\n## The most likely fix\n\nThere are two main fixes.\n\n### Fix A: conservative recovery fix\n\nKeep the older Gradio setup, but pin `huggingface_hub` below v1.\n\nAdd this to `requirements.txt`:\n\n\n    huggingface_hub<1.0\n\n\nFor this app, the dependency file would look like:\n\n\n    huggingface_hub<1.0\n    diffusers\n    transformers\n    accelerate\n    xformers\n    Pillow\n    qrcode\n    filelock\n    --extra-index-url https://download.pytorch.org/whl/cu118\n    torch\n\n\nThis is the safest first fix because it changes only the library version boundary that caused the import failure.\n\nThis is a **recovery fix** , not a full modernization. It says:\n\n> “Keep the old Gradio app working by keeping `huggingface_hub` on the old compatible API line.”\n\nThis is also the kind of fix seen in similar public cases where older apps broke after `huggingface_hub` 1.x removed `HfFolder`.\n\nRelevant references:\n\n  * Hugging Face Hub migration guide\n  * oobabooga issue explaining the same HfFolder failure\n  * Hugging Face evaluate issue after huggingface_hub 1.0.0\n\n\n\n* * *\n\n### Fix B: forward migration fix\n\nUpgrade Gradio to a version that no longer uses `HfFolder.get_token()`.\n\nA likely minimum target is:\n\n\n    sdk_version: 5.7.1\n\n\nor a newer tested Gradio version.\n\nThis is cleaner long-term because Gradio 5.7.1 includes the upstream fix:\n\n\n    Use get_token instead of HfFolder.get_token.\n\n\nReference:\n\n  * Gradio changelog\n\n\n\nHowever, I would **not** choose this as the first move unless you are maintaining the app. Upgrading Gradio can reveal other compatibility changes in:\n\n  * components,\n  * event handlers,\n  * OAuth/login behavior,\n  * custom CSS/JS behavior,\n  * queue behavior,\n  * history/profile UI,\n  * and ZeroGPU integration.\n\n\n\nSo the beginner-safe order is:\n\n\n    First:\n        add `huggingface_hub<1.0`\n\n    Then:\n        rebuild and see whether the app starts\n\n    Later:\n        consider a Gradio upgrade if you want a long-term maintained fork\n\n\n* * *\n\n## If these are not your Spaces\n\nIf the Spaces are not yours, you cannot directly fix the public page.\n\nYou cannot directly:\n\n  * edit `requirements.txt`,\n  * change `sdk_version`,\n  * run Factory rebuild,\n  * change hardware,\n  * remove OAuth,\n  * change ZeroGPU settings,\n  * or patch the source.\n\n\n\nSo your practical options are:\n\nOption | Control | Difficulty | Notes\n---|---|---|---\nWait for the owner/platform to fix it | Low | Very easy | Fine for casual use, unreliable if you need the tool now.\nUse another working tool | Low | Easy | Best if you only need similar output.\nDuplicate the Space | Medium/high | Medium | Lets you patch dependencies, but GPU/ZeroGPU matters.\nRun locally | High | Medium/hard | Best if you have an NVIDIA GPU and are willing to set up Python/CUDA.\n\nHugging Face’s docs explain that Spaces can be duplicated and configured, but duplicated Spaces generally start from basic CPU hardware unless you select/upgrade hardware.\n\nReferences:\n\n  * Manage Spaces with huggingface_hub\n  * Spaces Overview\n  * Spaces GPU documentation\n  * Spaces ZeroGPU documentation\n\n\n\n* * *\n\n## If you duplicate the Space\n\nIf you make your own duplicate, the first change I would make is only this:\n\n\n    huggingface_hub<1.0\n\n\nDo not upgrade everything at once.\n\nA good first `requirements.txt` patch would be:\n\n\n    huggingface_hub<1.0\n    diffusers\n    transformers\n    accelerate\n    xformers\n    Pillow\n    qrcode\n    filelock\n    --extra-index-url https://download.pytorch.org/whl/cu118\n    torch\n\n\nThen rebuild.\n\nIf the `HfFolder` error disappears, the diagnosis was correct.\n\nAfter that, a second error may appear. That does **not** mean the first fix was wrong. It means the app finally got past the first startup failure.\n\nPossible second-layer errors include:\n\n  * no GPU available,\n  * ZeroGPU quota or timeout,\n  * PyTorch / CUDA mismatch,\n  * `xformers` binary mismatch,\n  * model download failure,\n  * insufficient VRAM,\n  * OAuth/login behavior not working,\n  * or a Gradio UI compatibility issue.\n\n\n\n* * *\n\n## Important hardware note\n\nThis is a diffusion image-generation app. CPU-only execution is probably not a good experience.\n\nHugging Face ZeroGPU is a special shared-GPU runtime for Spaces. The ZeroGPU docs say it dynamically allocates and releases NVIDIA H200 GPUs for Spaces and uses the `@spaces.GPU` pattern.\n\nSo if you duplicate the app, make sure you understand the hardware:\n\n\n    CPU duplicate:\n        probably too slow or unusable for this app\n\n    GPU / ZeroGPU duplicate:\n        realistic\n\n\nIf you only get free CPU hardware, the app may start but generation may be painfully slow or fail.\n\n* * *\n\n## If you want to run it locally\n\nYou can probably run it locally, but this is only realistic if you have an NVIDIA GPU.\n\nThis app is written like a CUDA/GPU app. It loads diffusion components and moves the pipeline to CUDA. Local CPU-only use is likely to be very slow or impractical.\n\nBefore trying the app locally, check whether PyTorch can see your GPU:\n\n\n    python -c \"import torch; print(torch.__version__); print(torch.cuda.is_available())\"\n\n\nYou want:\n\n\n    True\n\n\nIf it prints:\n\n\n    False\n\n\nthen do not debug the app yet. Fix your PyTorch/CUDA installation first.\n\nReference:\n\n  * PyTorch local installation guide\n\n\n\n* * *\n\n## Local setup idea\n\nFor a conservative local setup, use Python 3.10 and install compatible packages.\n\nExample:\n\n\n    python -m venv venv\n    source venv/bin/activate\n    python -m pip install --upgrade pip\n\n\nOn Windows PowerShell, activation is usually:\n\n\n    .\\venv\\Scripts\\Activate.ps1\n\n\nThen install Gradio and the compatible Hub package:\n\n\n    pip install gradio==4.36.1 \"huggingface_hub<1.0\" diffusers transformers accelerate Pillow qrcode filelock\n\n\nInstall PyTorch separately using the official selector:\n\n  * PyTorch install selector\n\n\n\nI would initially avoid installing `xformers` unless needed, because `xformers` can be sensitive to the exact PyTorch/CUDA version. First make the app boot. Optimize later.\n\n* * *\n\n## Handling `import spaces` locally\n\nThe app uses Hugging Face ZeroGPU-style code:\n\n\n    import spaces\n\n    @spaces.GPU\n    def inference(...):\n        ...\n\n\nThat is meant for Hugging Face Spaces / ZeroGPU. Locally, you are not running inside the same ZeroGPU runtime.\n\nIf local execution fails with:\n\n\n    ModuleNotFoundError: No module named 'spaces'\n\n\nyou can create a tiny local file named `spaces.py` next to `app.py`:\n\n\n    def GPU(func=None, **kwargs):\n        def decorator(f):\n            return f\n\n        if callable(func):\n            return func\n\n        return decorator\n\n\nThis makes `@spaces.GPU` do nothing locally.\n\nThat is fine for a local GPU setup because your local machine already owns the GPU. You do not need Hugging Face’s ZeroGPU allocator.\n\nReference:\n\n  * Spaces ZeroGPU documentation\n\n\n\n* * *\n\n## Offline use: what is realistic?\n\n“Offline” is possible only after setup.\n\nThe first run needs internet to install packages and download model files. Later runs can use the local Hugging Face cache if all required files are already present.\n\nThe Hugging Face Hub download guide explains that Hub downloads are cached locally. The environment variable docs explain that `HF_HUB_OFFLINE=1` prevents HTTP calls and uses cached files only; if a needed cached file is missing, it raises an error.\n\nSo the realistic model is:\n\n\n    First run:\n        internet required\n        packages downloaded\n        model files downloaded\n        cache populated\n\n    Later runs:\n        can work offline if all required model files are cached\n\n\nDo not expect this to work offline from a fresh install.\n\nOffline mode examples:\n\n\n    export HF_HUB_OFFLINE=1\n    python app.py\n\n\nWindows Command Prompt:\n\n\n    set HF_HUB_OFFLINE=1\n    python app.py\n\n\nWindows PowerShell:\n\n\n    $env:HF_HUB_OFFLINE=\"1\"\n    python app.py\n\n\nReferences:\n\n  * Download files from the Hub\n  * HF Hub environment variables: HF_HUB_OFFLINE\n  * Transformers offline-mode notes\n\n\n\n* * *\n\n## Why I would not rewrite the model-loading code first\n\nThe app uses `@spaces.GPU`, and it may also move the model to CUDA at module/root level.\n\nThat can look strange if you are used to ordinary local Python scripts. But for ZeroGPU Spaces, Hugging Face documents a specific execution model around `@spaces.GPU`. So I would not start by moving model loading into the inference function.\n\nFirst fix the import/dependency error. Then handle any new runtime error separately.\n\nA safe debugging order is:\n\n\n    1. Fix `HfFolder` import crash.\n    2. Confirm the app starts.\n    3. Confirm models download/load.\n    4. Confirm CUDA/GPU is available.\n    5. Test one small generation.\n    6. Only then optimize speed, memory, duration, or UI behavior.\n\n\n* * *\n\n## Likely next issues after the `HfFolder` fix\n\nAfter adding `huggingface_hub<1.0`, you may uncover a second error. Common possibilities:\n\n### 1. ZeroGPU duration / timeout\n\nIf generation starts but times out, the app may need a longer ZeroGPU duration.\n\nExample patch:\n\n\n    @spaces.GPU(duration=120)\n    def inference(...):\n        ...\n\n\nReference:\n\n  * ZeroGPU documentation\n\n\n\n### 2. `xformers` mismatch\n\nIf the next error mentions compiled extensions, CUDA symbols, missing operators, or binary mismatch, `xformers` may not match the installed PyTorch version.\n\nA beginner-safe tactic is:\n\n\n    Get the app booting without `xformers` first.\n    Add `xformers` later only if needed.\n\n\n### 3. CUDA out of memory\n\nIf you see something like:\n\n\n    CUDA out of memory\n\n\nthen your GPU may not have enough VRAM for the current resolution / model / second pass.\n\nPossible mitigations:\n\n  * lower resolution,\n  * reduce inference steps,\n  * avoid the second 1024x1024 pass,\n  * use CPU offload,\n  * use a bigger GPU,\n  * or use a lighter workflow.\n\n\n\nReference:\n\n  * Diffusers memory optimization guide\n\n\n\n### 4. OAuth / login behavior\n\nThe app has Hugging Face OAuth-related behavior. That is part of why Gradio imports OAuth code. Locally, login/profile/history features may not behave the same as on Hugging Face Spaces.\n\nIf local generation works but login/history fails, that is a separate issue.\n\nReference:\n\n  * Gradio LoginButton docs\n\n\n\n* * *\n\n## My practical recommendation\n\nIf you only want to use the tool casually, I would not start with local setup. Use another working public tool or wait.\n\nIf you want this exact tool and some control, duplicate the Space and apply the conservative dependency fix:\n\n\n    huggingface_hub<1.0\n\n\nIf you want independence from the public Space, run it locally only if you have an NVIDIA GPU and are willing to set up Python, PyTorch, CUDA, and model downloads.\n\nMy ranking:\n\n\n    Lowest effort:\n        wait or use another working public tool\n\n    Best controlled non-local route:\n        duplicate Space + add `huggingface_hub<1.0` + use GPU/ZeroGPU\n\n    Best independent route:\n        local NVIDIA GPU setup\n\n    Worst beginner route:\n        trying to run this exact app locally on CPU only\n\n\n* * *\n\n## Final summary\n\n  * The error means old Gradio code is importing `HfFolder`, but the installed `huggingface_hub` no longer provides it.\n  * The app crashes during startup, before image generation begins.\n  * The most likely cause is dependency drift: old Gradio plus new `huggingface_hub`.\n  * The safest immediate fix is adding `huggingface_hub<1.0` to `requirements.txt`.\n  * The longer-term fix is upgrading Gradio to a version that uses `get_token()` instead of `HfFolder.get_token()`, such as Gradio 5.7.1 or newer.\n  * If the Space is not yours, you cannot fix the original directly.\n  * You can duplicate it, but diffusion needs GPU/ZeroGPU hardware.\n  * You can run it locally, but realistically you want an NVIDIA GPU.\n  * Offline use means “download once, then run from cache,” not “run from a fresh install without internet.”\n\n",
  "title": "Runtime Errror?"
}