My space was paused and 503 when I restart

Beginners
1

after just a few minutes after I created my new space,my space was paused and 503 when restart.，

my code file:

FROM Package hajimi · GitHub
EXPOSE 7860
CMD [“uvicorn”, “app.main:app”, “–host”, “0.0.0.0”, “–port”, “7860”]
1 Like
2

That information alone isn’t enough to pinpoint the problem…

A Hugging Face Space shows 503 on restart when the platform cannot get your container into a healthy “listening web server” state. In practice that means one of these happened:

  1. The container process exits (crash, bad command, missing module, missing executable).
  2. The process stays up, but it does not listen on the expected host and port.
  3. Less common: HF infra is stuck and your Space never really starts.

HF’s own Docker Spaces docs assume your app serves HTTP on a single exposed port (default 7860, configurable via app_port). (Hugging Face)
And forum guidance matches the symptom: “Paused + 503 on restart” usually means the restart failed because the container did not start correctly. (Hugging Face Forums)

What is “paused” vs “503”

  • Paused / sleeping can be normal. Free CPU Spaces auto-sleep after long inactivity (docs mention 48 hours on cpu-basic). (Hugging Face)
  • 503 when you click restart is not normal sleep. It means the container failed to come up (or HF could not route to it). (Hugging Face Forums)

Your “a few minutes after creation” pattern is much more consistent with “container dies quickly” than with inactivity sleep. (Hugging Face)

The biggest bug in your Dockerfile

You used –host and –port (en dash), not --host and --port (two ASCII hyphens)

That character difference matters. Uvicorn’s CLI options are --host and --port. (uvicorn.dev)
If you pass –host, uvicorn treats it as an unknown argument and exits. When the process exits, the container stops. HF then serves 503.

Fix it:

FROM ghcr.io/googolplex35/hajimi:latest
EXPOSE 7860
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

Uvicorn also documents the required import-string format "<module>:<attribute>" (your app.main:app). (uvicorn.dev)

Other common causes (still likely if 503 persists)

1) uvicorn is not installed in that base image

If the image does not contain uvicorn, Docker will fail with “executable file not found” and exit immediately. That produces the same 503 symptom.

How to confirm: open Runtime logs on the Space page and look at the last lines.

2) app.main:app does not exist inside the container

Your Dockerfile does not COPY your repo code into the image. So app/main.py must already be inside ghcr.io/googolplex35/hajimi:latest. If it is not, you will get ModuleNotFoundError: No module named 'app' and the container exits.

Again, runtime logs will show this clearly.

3) Port mismatch or binding to localhost

HF routes traffic to the single exposed port (default 7860 unless you set app_port). (Hugging Face)
If your app binds to 127.0.0.1 or a different port, HF cannot reach it and you see 503.

Uvicorn expects --host 0.0.0.0 for “listen on all interfaces.” (uvicorn.dev)

4) Permissions and “run as non-root” assumptions

Many Docker Spaces examples create a UID 1000 user and run as that user to avoid permission problems. (Docker)
If your base image assumes root-only paths (writing under /root, installing at runtime, etc.), it can crash or misbehave.

5) HF-side stuck build or stuck restart (less common, but real)

There are recent forum reports where Docker Spaces get stuck “Paused” and any restart yields 503 even with correct code. A common workaround is duplicating/recreating the Space or toggling settings to force a reschedule. (Hugging Face Forums)

6) Policy blocks (rare, but possible)

Some users report 503 tied to prohibited libraries or policy enforcement. If logs hint at blocking or the Space never runs even with a minimal app, this is a possibility. (Hugging Face Forums)

A safer “reference” Dockerfile (if you actually want to run code from the repo)

If your FastAPI code is in the Space repo and not baked into the base image, use a Dockerfile that installs deps and copies code (this mirrors common Spaces guidance): (Docker)

FROM python:3.11-slim

RUN useradd -m -u 1000 user
USER user
ENV HOME=/home/user \
    PATH=/home/user/.local/bin:$PATH
WORKDIR $HOME/app

COPY --chown=user requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY --chown=user . .

CMD ["sh", "-c", "uvicorn app.main:app --host 0.0.0.0 --port ${PORT:-7860}"]

Notes:

  • HF Docker Spaces default external port is 7860, and you can set app_port in README.md YAML if you need a different port. (Hugging Face)
  • The ${PORT:-7860} pattern is just a convenience. Hardcoding 7860 is also fine if your Space uses app_port: 7860.

How to debug quickly (do this even after fixing the dash)

  1. Go to your Space page. Click the status badge. Open Logs.

  2. If the error is in the build, look at Build logs. If it crashes at runtime, look at Runtime logs.

  3. Look specifically for:

    • “unrecognized arguments” (dash typo)
    • “executable file not found” (uvicorn missing)
    • ModuleNotFoundError (wrong import path or code not in image)

  4. Reproduce locally with the same image and command:

    • Build your Dockerfile locally, run docker run -p 7860:7860 ..., and see the exact stderr traceback.

References worth keeping open

  • HF Docker Spaces docs (ports, app_port): (Hugging Face)
  • HF “Paused + 503 restart failed” explanation (forum): (Hugging Face Forums)
  • Uvicorn CLI flags --host and --port: (uvicorn.dev)
  • Typical Docker Spaces FastAPI Dockerfile with UID 1000 and port 7860: (Docker)
  • HF sleep/pause behavior (why “paused” can be normal): (Hugging Face)

Summary

  • Your Dockerfile has a high-probability fatal typo: –host/–port must be --host/--port. (uvicorn.dev)
  • If 503 remains, check logs for: missing uvicorn, missing app.main:app, wrong port, or permission issues. (Hugging Face)
  • If logs look “stuck/empty” and restarts always 503, it may be HF infra. Duplicating the Space is a known workaround reported by users. (Hugging Face Forums)