{
  "$type": "site.standard.document",
  "bskyPostRef": {
    "cid": "bafyreigfe5y7eeyutgwf6kiphvzzpvbvtzhoecuyskjdyhnmgnro57ufbu",
    "uri": "at://did:plc:pgryn3ephfd2xgft23qokfzt/app.bsky.feed.post/3mhwoto3uvsm2"
  },
  "path": "/t/my-hugging-face-space-keep-starting/174616#post_7",
  "publishedAt": "2026-03-26T00:32:41.000Z",
  "site": "https://discuss.huggingface.co",
  "tags": [
    "Hugging Face Forums",
    "Hugging Face",
    "GitHub",
    "@app.head"
  ],
  "textContent": "I tried debugging the code for that Space, but since the issue can’t be explained by the code alone, I think both factors are to blame.\n\n* * *\n\n## Bottom line\n\nFor **SAkizuki/DanbooruSearch** , the most likely explanation is **two problems overlapping** :\n\n  1. **A real app-side HTTP/readiness edge case** : the root path was returning **405** for `HEAD /`, and after adding an explicit `@app.head('/')` handler it returned **200**.\n  2. **A Hugging Face platform-side status/control-plane issue** : in the same incident, the app logs looked normal, the direct `.hf.space` URL worked, and another user reported the same issue, yet the Space page still stayed on **Starting**. The Space is currently shown as **Running**. (Hugging Face Forums)\n\n\n\n## What happened in this case\n\nThe thread shows a very specific timeline. At first, the author only saw the platform startup banner in logs and suspected the script was not running. Later, the logs clearly showed the script starting, NiceGUI becoming ready, the engine loading, and full warmup finishing in about **37.70 seconds**. The author also said the direct URL `https://sakizuki-danboorusearch.hf.space/` worked normally even while the Space page still showed **Starting**. Another forum user replied that they were seeing the same issue. (Hugging Face Forums)\n\nThat combination matters. When the direct app URL works and the logs show the app fully initialized, this is **not well explained** by “the container never started.” It points instead to a mismatch between **the app actually running** and **Hugging Face deciding the Space is healthy enough to flip from Starting to Running**. (Hugging Face Forums)\n\n## Why the usual “wrong port” answer is probably not the main cause here\n\nFor this Space, the current repo wiring is internally consistent:\n\n  * the README metadata says `sdk: docker` and `app_port: 7860`\n  * the Dockerfile exposes `7860` and runs `python ui_nicegui.py`\n  * `platform_utils.py` returns `0.0.0.0, 7860` in cloud mode\n  * `ui.run()` uses that host and port. (Hugging Face)\n\n\n\nThat matches Hugging Face’s Docker Spaces guidance, which documents `app_port: 7860` as the default external port for Docker Spaces. So the classic Docker mistake of “the app is bound to the wrong host or wrong port” does **not** look like the best fit for the final observed state of this Space. (Hugging Face)\n\n## The strongest app-side clue: `HEAD /` returned 405\n\nThis is the most concrete technical clue in the thread. The author says that `curl -Ik https://sakizuki-danboorusearch.hf.space/` initially returned **HTTP/1.1 405 Method Not Allowed**. They then added:\n\n\n    @app.head('/')\n    async def head_root():\n        return PlainTextResponse(\"\")\n\n\nAfter that, the same `curl -Ik` returned **HTTP/1.1 200 OK**. The live code now includes that handler. (Hugging Face Forums)\n\nThat matters because FastAPI has a long-standing issue where a route that handles `GET` may still return **405** for `HEAD` unless you add explicit handling. The FastAPI issue tracker describes exactly this behavior and shows manual `@app.head(\"/\")` as the workaround. So the `405` was not random. It is a known framework-level pitfall. (GitHub)\n\n## What that probably means here\n\nThe thread does **not** prove that Hugging Face’s health check definitely uses `HEAD /`. But it does prove something narrower and more useful: **one probeable path on the live app was returning the wrong status for HEAD requests** , and fixing that changed the response from 405 to 200 right before the Space recovered. That makes the missing `HEAD /` support a **plausible and important app-side cause** for this specific incident. (Hugging Face Forums)\n\n## Why I still would not blame only the app\n\nBecause the thread also shows behavior that is hard to explain with only an app bug:\n\n  * logs were sometimes reduced to only the platform banner line\n  * logs were later completely normal\n  * the direct `.hf.space` URL worked\n  * another user reported the same issue in the same thread\n  * the author says they did nothing else and it “suddenly worked.” (Hugging Face Forums)\n\n\n\nThat pattern strongly suggests that **Hugging Face’s status/control layer was at least part of the story**. In plain terms, the app may have been fine enough to serve traffic, while the platform UI or health registration temporarily failed to recognize that cleanly. (Hugging Face Forums)\n\n## What was probably _not_ the main cause\n\n### Not a slow-start timeout\n\nHugging Face documents `startup_duration_timeout` as the maximum allowed startup time before a Space is marked unhealthy, with a default of **30 minutes**. In the incident logs, the Space finished full warmup in about **37.70 seconds**. That is nowhere near the documented default timeout. (Hugging Face)\n\n### Probably not a broken Docker launch command\n\nThe current repository has the normal Docker pieces in place: `sdk: docker`, `app_port: 7860`, `EXPOSE 7860`, and `CMD [\"python\", \"ui_nicegui.py\"]`. The app also explicitly binds to `0.0.0.0:7860` in cloud mode. That is the opposite of what you usually see in a simple launch misconfiguration. (Hugging Face)\n\n## The most likely root-cause picture\n\nThe cleanest explanation is this:\n\n  * **Primary app-side issue:** root `HEAD` requests were not handled correctly, producing **405** instead of **200**.\n  * **Concurrent platform-side issue:** Hugging Face’s status layer appears to have been inconsistent, because the app was sometimes clearly alive while the UI still showed **Starting** , and another user reported the same symptom. (Hugging Face Forums)\n\n\n\nSo this was probably **not** “just your code” and **not** “just Hugging Face.” It looks more like **a real readiness bug plus a platform-state glitch**. (Hugging Face Forums)\n\n## Solutions for this Space\n\n### 1. Keep the explicit `@app.head('/')` handler\n\nThis is already in the live code and should stay. It is the most defensible fix because it directly addressed an observed bad response on the live Space. (Hugging Face)\n\n### 2. Add lightweight `/healthz` and `/readyz` endpoints\n\nRight now, the app mounts a FastAPI sub-app at `/api`, and `/api/health` exists. But that health route calls `DanbooruTagger.get_instance()`, which means the health endpoint can itself trigger heavy initialization work. That is not ideal for a liveness check. A better design is:\n\n  * `/healthz`: returns 200 immediately if the web process is alive\n  * `/readyz`: returns whether the model/data layer is actually ready. (Hugging Face)\n\n\n\n### 3. Keep Docker wiring aligned exactly as it is\n\nFor Docker Spaces, Hugging Face expects the external `app_port` to match what the app serves. This repo is already aligned on `7860`, so this part should be preserved. (Hugging Face)\n\n### 4. Only use `startup_duration_timeout` if startup later becomes genuinely slow\n\nIf future versions take much longer to initialize, Hugging Face supports `startup_duration_timeout` in the README metadata. But for this incident, startup time was not the main problem. (Hugging Face)\n\n## Practical debugging checklist for the next time this happens\n\nIf this Space gets stuck on **Starting** again, the fastest checks are:\n\n  1. `curl -I https://sakizuki-danboorusearch.hf.space/`\nIf this fails or returns 405 again, that is immediately suspicious.\n  2. Open the direct `.hf.space` URL.\nIf it works but the Space page still says Starting, the platform status layer is probably lagging reality.\n  3. Compare logs with actual reachability.\nIf logs look bad but the direct app works, do not assume the app is dead.\n  4. Check lightweight health endpoints once they exist.\nThat will separate “web server is up” from “engine is ready.” (Hugging Face Forums)\n\n\n\n## Final answer\n\nFor **SAkizuki/DanbooruSearch** , the best explanation is:\n\n  * the app had a **real readiness/HTTP compatibility issue** at the root path because `HEAD /` returned 405, and\n  * Hugging Face likely had **some platform-side status inconsistency** at the same time, because the app could still run and serve normally while the Space page stayed on **Starting**. (Hugging Face Forums)\n\n\n\nThe Space is now **Running** , and the live repo already contains the main defensive fix: explicit `HEAD /` support. The next useful hardening step is to add **separate lightweight health and readiness endpoints** so that future incidents are easier to diagnose. (Hugging Face)",
  "title": "My Hugging Face Space keep starting"
}