{
  "$type": "site.standard.document",
  "bskyPostRef": {
    "cid": "bafyreihswayrxpdojuppcni3qv4qtgdwefknuqtjqxdjka6trukawd7mqi",
    "uri": "at://did:plc:pgryn3ephfd2xgft23qokfzt/app.bsky.feed.post/3mj575lahhi22"
  },
  "path": "/t/how-to-fix-space-stuck-on-building-in-hugging-face-spaces/175119#post_2",
  "publishedAt": "2026-04-10T09:03:34.000Z",
  "site": "https://discuss.huggingface.co",
  "tags": [
    "Hugging Face",
    "Hugging Peace Status",
    "GitHub",
    "Hugging Face Forums"
  ],
  "textContent": "Just too many possible scenarios… and this isn’t even all of them…\n\n* * *\n\nHere is one decision tree that covers the main cases.\n\nA Space can stay on `Building` for several different reasons because Spaces are not just “run my script.” Hugging Face reads the `README.md` YAML, builds the image, provisions a VM/container, and then waits for the app to become healthy. For Docker Spaces, `app_port` defaults to `7860`. Spaces can also be marked unhealthy if startup exceeds `startup_duration_timeout`, which defaults to 30 minutes. (Hugging Face)\n\n# Decision tree: Hugging Face Space stuck on `Building`\n\n**Start**\n\n**1. Check the status page first.**\nIf **Spaces** or **Spaces Proxy** is degraded, treat it as a platform incident first. Do not churn code yet. The status page exposes those components separately. (Hugging Peace Status)\n\n**If the status page is normal, go to 2.**\n\n* * *\n\n## 2. Open the logs\n\n**2A. Are the logs empty, or do you only see something like`Build queued` with no real build output?**\nIf yes, go to **3**. Public reports and a current GitHub issue show this exact pattern for Docker Spaces: valid Dockerfile, works locally, but no build logs appear and the Space never really starts. (GitHub)\n\n**2B. Do you see a concrete error line?**\nIf yes, jump to the matching branch below:\n\n  * `Repository storage limit reached (Max: 1 GB)` or `Error while cloning repository` → **4**\n  * `Scheduling failure: not enough hardware capacity` or `Unable to schedule` → **5**\n  * `503 Something went wrong when restarting this Space` → **6**\n  * `ModuleNotFoundError`, pip conflicts, missing package, bad import → **7**\n  * `E: Package '...' has no installation candidate` or `exit code: 100` during apt install → **8**\n  * build finishes but app never becomes healthy → **9**\n\n\n\n* * *\n\n## 3. Empty logs or only `Build queued`\n\n### 3A. Is this happening to multiple Spaces, or are other users reporting the same thing right now?\n\nIf yes, treat it as a **platform or scheduler incident**. Forum cases show long `Build queued` states, empty logs, and later recovery without user code changes. Another recurring pattern is capacity-related failures surfacing around the same time. (Hugging Face Forums)\n\n**What to do**\n\n  * Wait and monitor the status page and forum.\n  * Save the Space URL, timestamp, hardware type, and a screenshot of the empty logs.\n  * Avoid major code rewrites until the incident clears. (Hugging Peace Status)\n\n\n\n### 3B. Is it only one Space, while other Spaces or a fresh clone work?\n\nIf yes, treat it as a **Space-specific stuck state** first. Public reports and issue #3452 show Spaces where the original slug is wedged while a fresh Space or clone works. (GitHub)\n\n**What to do**\n\n  * Use the deeper reset button in Settings, currently labeled **Factory rebuild** in the live UI.\n  * Push a tiny no-op commit.\n  * Duplicate or recreate the Space under a new slug.\n  * If a fresh minimal Space also fails, escalate to Hugging Face support as a likely HF-side issue. (GitHub)\n\n\n\n* * *\n\n## 4. `Repository storage limit reached (Max: 1 GB)` or clone failure\n\nTreat this as a **repo-history / cloneability** problem, not a normal runtime bug. Public Space threads show this exact error and also report that restart/reset may still leave the Space in endless building because the repo history is the real problem. (Hugging Face Forums)\n\n### Why it happens\n\nA Space repo is Git-based, but Space disk is ephemeral, and Storage Buckets are the recommended persistent storage for larger mutable data. Buckets are non-versioned and mutable, unlike Git repos. (Hugging Face)\n\n### What to do\n\n  * Move large weights, checkpoints, logs, and datasets out of the Space repo.\n  * Use a model repo, dataset repo, or Storage Bucket instead.\n  * If the repo history is already bloated, rewrite history or create a fresh clean Space repo and copy only the current code. (Hugging Face)\n\n\n\n### Error strings to watch for\n\n  * `Repository storage limit reached (Max: 1 GB)`\n  * `batch response: Repository storage limit reached (Max: 1 GB)`\n  * `Error while cloning repository` (Hugging Face Forums)\n\n\n\n* * *\n\n## 5. `Scheduling failure: not enough hardware capacity` or `Unable to schedule`\n\nTreat this as a **capacity bottleneck** , not a dependency bug. ZeroGPU is shared infrastructure that dynamically allocates NVIDIA H200 GPUs, and public forum guidance explicitly separates “Build queued” / “not enough hardware capacity” from ordinary app problems. (Hugging Face)\n\n### What to do\n\n  * Retry later.\n  * Switch hardware tier if possible.\n  * Duplicate/recreate if you want to see whether a different worker picks it up.\n  * Do not keep changing dependencies if the dominant error is capacity. (Hugging Face Forums)\n\n\n\n### Error strings to watch for\n\n  * `Scheduling failure: not enough hardware capacity`\n  * `Unable to schedule`\n  * long `Build queued` during peak periods (Hugging Face Forums)\n\n\n\n* * *\n\n## 6. `503 Something went wrong when restarting this Space`\n\nA `503` is a **symptom** , not a root cause. It can mean startup crash, unhealthy container, proxy mismatch, scheduler trouble, or in some cases an intentional block. Public threads show all of these. (Hugging Face Forums)\n\n### 6A. Do runtime logs show a startup crash or main-process failure?\n\nIf yes, treat it as a **startup / runtime failure**. One public example shows `supervisord.conf` parsing failure causing the container to exit immediately, which then surfaces as a 503 on restart. (Hugging Face Forums)\n\n**What to do**\n\n  * Fix the startup command or supervisor config.\n  * Check whether the main server process exits immediately.\n  * Check RAM pressure and startup-time downloads.\n  * Re-test with the smallest possible app. (Hugging Face Forums)\n\n\n\n### 6B. Is this a Docker Space, and could the proxy be checking the wrong port or wrong surface?\n\nIf yes, treat it as a **port / health / bind-address** issue. Docker Spaces use `sdk: docker`, and the external port defaults to `7860`. A public 503 thread also highlights mode/port mismatches as a top cause. (Hugging Face)\n\n**What to do**\n\n  * Confirm `sdk: docker` in `README.md`.\n  * Confirm the app actually binds to the same `app_port`.\n  * Bind to `0.0.0.0`, not localhost-only.\n  * Increase `startup_duration_timeout` if startup is legitimately slow. (Hugging Face)\n\n\n\n### 6C. Are logs empty, the Space is paused, restart gives 503, and other Docker Spaces work?\n\nThat pattern leans toward **builder/scheduler/Space-state trouble** , not necessarily your code. Public reports describe this exact cluster. (Hugging Face Forums)\n\n**What to do**\n\n  * Factory rebuild.\n  * No-op commit.\n  * Duplicate/recreate under a new slug.\n  * Escalate if even a fresh minimal Space behaves the same. (GitHub)\n\n\n\n### 6D. Has HF support or your org explicitly indicated blocking, suspicious behavior, or restricted access?\n\nIf yes, stop technical debugging and treat it as a **policy or access-control** issue. Hugging Face’s Content Policy says the team may disable access, restrict interactions, or suspend content/accounts. Enterprise orgs can also block `/spaces/*` via Content Access Policy. (Hugging Face)\n\n**What to do**\n\n  * Review the Space against the Content Policy.\n  * Remove risky or prohibited behavior.\n  * If you are in an enterprise org, check whether `/spaces/*` is blocked by org policy.\n  * Contact HF support or your org admin. (Hugging Face)\n\n\n\n### Error strings to watch for\n\n  * `503 Something went wrong when restarting this Space`\n  * page shows `Paused` plus restart 503\n  * router/proxy works but cannot attach to a healthy container\n  * “suspicious” or blocked by policy/access rules (Hugging Face Forums)\n\n\n\n* * *\n\n## 7. `ModuleNotFoundError`, pip conflicts, or dependency install failures\n\nTreat this as a **normal dependency/config** issue. Hugging Face documents the standard dependency layout:\n\n  * `requirements.txt` for Python packages,\n  * `pre-requirements.txt` for things that must be installed before the main requirements,\n  * `packages.txt` for Debian packages via `apt-get install`. (Hugging Face)\n\n\n\n### What to do\n\n  * Clean `requirements.txt`.\n  * Add only genuinely needed packages.\n  * Use `pre-requirements.txt` if installation order matters.\n  * Put only OS packages in `packages.txt`.\n  * Verify the YAML block in `README.md`: `sdk`, `python_version`, `sdk_version`, `app_file`. (Hugging Face)\n\n\n\n### Error strings to watch for\n\n  * `ModuleNotFoundError`\n  * `No module named ...`\n  * pip version-resolution failures\n  * import-time tracebacks during startup or build (Hugging Face)\n\n\n\n* * *\n\n## 8. `E: Package '...' has no installation candidate` or `exit code: 100`\n\nTreat this as a **Docker / base-image / OS package** issue. Public reports show `libgl1-mesa-glx` failing with `exit code: 100`, including cases where the Space had worked the day before. (Hugging Face Forums)\n\n### What to do\n\n  * Update obsolete apt package names.\n  * Reduce system packages to the minimum.\n  * Rebuild after small Dockerfile changes.\n  * Check permission rules too: Docker Spaces run as user ID `1000`, and HF recommends setting `WORKDIR`, switching to the user before pip operations, and copying files with the correct ownership. (Hugging Face Forums)\n\n\n\n### Error strings to watch for\n\n  * `E: Package 'libgl1-mesa-glx' has no installation candidate`\n  * `did not complete successfully: exit code: 100` (Hugging Face Forums)\n\n\n\n* * *\n\n## 9. Build succeeds, but the app never becomes healthy\n\nTreat this as a **startup / health-check** issue. Spaces can be marked unhealthy if startup exceeds the configured timeout, and Docker Spaces must actually expose the right app port. (Hugging Face)\n\n### What to do\n\n  * Check `app_port` and the actual listening port.\n  * Check bind address.\n  * Reduce the startup path to the smallest possible working app.\n  * Move large startup downloads out of the critical path.\n  * If startup is slow because you need large Hub assets, consider `preload_from_hub` to shift downloads to build time.\n  * Raise `startup_duration_timeout` if the startup is legitimately slow and otherwise healthy. (Hugging Face)\n\n\n\n### Helpful knobs\n\n  * `app_port`\n  * `startup_duration_timeout`\n  * `preload_from_hub` (Hugging Face)\n\n\n\n* * *\n\n## 10. If you still cannot classify it\n\nUse **Spaces Dev Mode** if you have access to it. HF documents that Dev Mode skips repeated image rebuilds, lets you SSH into the running container, and makes iteration faster. Requirements are not auto-installed there, so you may need to run `pip install` manually from SSH or VS Code. (Hugging Face)\n\n### What to do\n\n  * Enable Dev Mode.\n  * Inspect the live container.\n  * Run the app manually.\n  * Check open ports, startup logs, and memory usage.\n  * Persist any successful fixes with a git commit from inside the container. (Hugging Face)\n\n\n\n* * *\n\n# Short cheat sheet by error code / message\n\n**`Build queued` + empty logs**\nLikely scheduler/Space-state/infra issue. Try Factory rebuild, no-op commit, clone/new slug, then support if a minimal Space also fails. (GitHub)\n\n**`Repository storage limit reached (Max: 1 GB)`**\nSpace repo history is too large. Move artifacts out of the Space repo. Use Storage Buckets or other repos. (Hugging Face Forums)\n\n**`Error while cloning repository`**\nOften same family as repo-size/history issues. Audit Git/LFS history, not just the latest tree. (Hugging Face Forums)\n\n**`Scheduling failure: not enough hardware capacity` / `Unable to schedule`**\nCapacity bottleneck. Retry later or switch hardware. (Hugging Face Forums)\n\n**HTTP`503` on restart**\nCould be startup crash, wrong port, wrong bind address, build/scheduler glitch, or an intentional block. Use the 503 branch above. (Hugging Face Forums)\n\n**`ModuleNotFoundError` / pip conflict**\nFix `requirements.txt`, `pre-requirements.txt`, `packages.txt`, and the `README.md` YAML. (Hugging Face)\n\n**`E: Package '...' has no installation candidate` / `exit code: 100`**\nDocker base-image / apt package issue. Update package names and simplify the Dockerfile. (Hugging Face Forums)\n\n* * *\n\n# Final rule\n\nTreat “stuck on `Building`” as a **classification problem** first.\n\n  * **Status page / many users affected** → incident path. (Hugging Peace Status)\n  * **Empty logs / only queue line** → scheduler or wedged Space path. (GitHub)\n  * **1 GB / clone errors** → repo-history path. (Hugging Face Forums)\n  * **Capacity messages** → hardware-scheduler path. (Hugging Face Forums)\n  * **503 with crash clues** → startup/runtime path. (Hugging Face Forums)\n  * **Blocked / suspicious / org URL policy** → policy or access-control path. (Hugging Face)\n\n",
  "title": "How to Fix “Space Stuck on Building” in Hugging Face Spaces"
}