How to Fix “Space Stuck on Building” in Hugging Face Spaces

Beginners
2

Just too many possible scenarios… and this isn’t even all of them…

Here is one decision tree that covers the main cases.

A 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)

Decision tree: Hugging Face Space stuck on Building

Start

1. Check the status page first.
If 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)

If the status page is normal, go to 2.

2. Open the logs

2A. Are the logs empty, or do you only see something like Build queued with no real build output?
If 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)

2B. Do you see a concrete error line?
If yes, jump to the matching branch below:

  • Repository storage limit reached (Max: 1 GB) or Error while cloning repository → 4
  • Scheduling failure: not enough hardware capacity or Unable to schedule → 5
  • 503 Something went wrong when restarting this Space → 6
  • ModuleNotFoundError, pip conflicts, missing package, bad import → 7
  • E: Package '...' has no installation candidate or exit code: 100 during apt install → 8
  • build finishes but app never becomes healthy → 9

3. Empty logs or only Build queued

3A. Is this happening to multiple Spaces, or are other users reporting the same thing right now?

If 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)

What to do

  • Wait and monitor the status page and forum.
  • Save the Space URL, timestamp, hardware type, and a screenshot of the empty logs.
  • Avoid major code rewrites until the incident clears. (Hugging Peace Status)

3B. Is it only one Space, while other Spaces or a fresh clone work?

If 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)

What to do

  • Use the deeper reset button in Settings, currently labeled Factory rebuild in the live UI.
  • Push a tiny no-op commit.
  • Duplicate or recreate the Space under a new slug.
  • If a fresh minimal Space also fails, escalate to Hugging Face support as a likely HF-side issue. (GitHub)

4. Repository storage limit reached (Max: 1 GB) or clone failure

Treat 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)

Why it happens

A 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)

What to do

  • Move large weights, checkpoints, logs, and datasets out of the Space repo.
  • Use a model repo, dataset repo, or Storage Bucket instead.
  • If the repo history is already bloated, rewrite history or create a fresh clean Space repo and copy only the current code. (Hugging Face)

Error strings to watch for

  • Repository storage limit reached (Max: 1 GB)
  • batch response: Repository storage limit reached (Max: 1 GB)
  • Error while cloning repository (Hugging Face Forums)

5. Scheduling failure: not enough hardware capacity or Unable to schedule

Treat 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)

What to do

  • Retry later.
  • Switch hardware tier if possible.
  • Duplicate/recreate if you want to see whether a different worker picks it up.
  • Do not keep changing dependencies if the dominant error is capacity. (Hugging Face Forums)

Error strings to watch for

  • Scheduling failure: not enough hardware capacity
  • Unable to schedule
  • long Build queued during peak periods (Hugging Face Forums)

6. 503 Something went wrong when restarting this Space

A 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)

6A. Do runtime logs show a startup crash or main-process failure?

If 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)

What to do

  • Fix the startup command or supervisor config.
  • Check whether the main server process exits immediately.
  • Check RAM pressure and startup-time downloads.
  • Re-test with the smallest possible app. (Hugging Face Forums)

6B. Is this a Docker Space, and could the proxy be checking the wrong port or wrong surface?

If 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)

What to do

  • Confirm sdk: docker in README.md.
  • Confirm the app actually binds to the same app_port.
  • Bind to 0.0.0.0, not localhost-only.
  • Increase startup_duration_timeout if startup is legitimately slow. (Hugging Face)

6C. Are logs empty, the Space is paused, restart gives 503, and other Docker Spaces work?

That pattern leans toward builder/scheduler/Space-state trouble, not necessarily your code. Public reports describe this exact cluster. (Hugging Face Forums)

What to do

  • Factory rebuild.
  • No-op commit.
  • Duplicate/recreate under a new slug.
  • Escalate if even a fresh minimal Space behaves the same. (GitHub)

6D. Has HF support or your org explicitly indicated blocking, suspicious behavior, or restricted access?

If 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)

What to do

  • Review the Space against the Content Policy.
  • Remove risky or prohibited behavior.
  • If you are in an enterprise org, check whether /spaces/* is blocked by org policy.
  • Contact HF support or your org admin. (Hugging Face)

Error strings to watch for

  • 503 Something went wrong when restarting this Space
  • page shows Paused plus restart 503
  • router/proxy works but cannot attach to a healthy container
  • “suspicious” or blocked by policy/access rules (Hugging Face Forums)

7. ModuleNotFoundError, pip conflicts, or dependency install failures

Treat this as a normal dependency/config issue. Hugging Face documents the standard dependency layout:

  • requirements.txt for Python packages,
  • pre-requirements.txt for things that must be installed before the main requirements,
  • packages.txt for Debian packages via apt-get install. (Hugging Face)

What to do

  • Clean requirements.txt.
  • Add only genuinely needed packages.
  • Use pre-requirements.txt if installation order matters.
  • Put only OS packages in packages.txt.
  • Verify the YAML block in README.md: sdk, python_version, sdk_version, app_file. (Hugging Face)

Error strings to watch for

  • ModuleNotFoundError
  • No module named ...
  • pip version-resolution failures
  • import-time tracebacks during startup or build (Hugging Face)

8. E: Package '...' has no installation candidate or exit code: 100

Treat 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)

What to do

  • Update obsolete apt package names.
  • Reduce system packages to the minimum.
  • Rebuild after small Dockerfile changes.
  • 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)

Error strings to watch for

  • E: Package 'libgl1-mesa-glx' has no installation candidate
  • did not complete successfully: exit code: 100 (Hugging Face Forums)

9. Build succeeds, but the app never becomes healthy

Treat 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)

What to do

  • Check app_port and the actual listening port.
  • Check bind address.
  • Reduce the startup path to the smallest possible working app.
  • Move large startup downloads out of the critical path.
  • If startup is slow because you need large Hub assets, consider preload_from_hub to shift downloads to build time.
  • Raise startup_duration_timeout if the startup is legitimately slow and otherwise healthy. (Hugging Face)

Helpful knobs

  • app_port
  • startup_duration_timeout
  • preload_from_hub (Hugging Face)

10. If you still cannot classify it

Use 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)

What to do

  • Enable Dev Mode.
  • Inspect the live container.
  • Run the app manually.
  • Check open ports, startup logs, and memory usage.
  • Persist any successful fixes with a git commit from inside the container. (Hugging Face)

Short cheat sheet by error code / message

Build queued + empty logs
Likely scheduler/Space-state/infra issue. Try Factory rebuild, no-op commit, clone/new slug, then support if a minimal Space also fails. (GitHub)

Repository storage limit reached (Max: 1 GB)
Space repo history is too large. Move artifacts out of the Space repo. Use Storage Buckets or other repos. (Hugging Face Forums)

Error while cloning repository
Often same family as repo-size/history issues. Audit Git/LFS history, not just the latest tree. (Hugging Face Forums)

Scheduling failure: not enough hardware capacity / Unable to schedule
Capacity bottleneck. Retry later or switch hardware. (Hugging Face Forums)

HTTP 503 on restart
Could be startup crash, wrong port, wrong bind address, build/scheduler glitch, or an intentional block. Use the 503 branch above. (Hugging Face Forums)

ModuleNotFoundError / pip conflict
Fix requirements.txt, pre-requirements.txt, packages.txt, and the README.md YAML. (Hugging Face)

E: Package '...' has no installation candidate / exit code: 100
Docker base-image / apt package issue. Update package names and simplify the Dockerfile. (Hugging Face Forums)

Final rule

Treat “stuck on Building” as a classification problem first.

build_stuck_flowchart
build_stuck_flowchart1216×1294 270 KB