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.
Bottom line
For SAkizuki/DanbooruSearch, the most likely explanation is two problems overlapping:
- 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.
- 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)
What happened in this case
The 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://huggingface.co/proxy/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)
That 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)
Why the usual “wrong port” answer is probably not the main cause here
For this Space, the current repo wiring is internally consistent:
- the README metadata says
sdk: docker and app_port: 7860
- the Dockerfile exposes
7860 and runs python ui_nicegui.py
platform_utils.py returns 0.0.0.0, 7860 in cloud modeui.run() uses that host and port. (Hugging Face)
That 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)
The strongest app-side clue: HEAD / returned 405
This is the most concrete technical clue in the thread. The author says that curl -Ik https://huggingface.co/proxy/sakizuki-danboorusearch.hf.space/ initially returned HTTP/1.1 405 Method Not Allowed. They then added:
@app.head('/')
async def head_root():
return PlainTextResponse("")
After that, the same curl -Ik returned HTTP/1.1 200 OK. The live code now includes that handler. (Hugging Face Forums)
That 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)
What that probably means here
The 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)
Why I still would not blame only the app
Because the thread also shows behavior that is hard to explain with only an app bug:
- logs were sometimes reduced to only the platform banner line
- logs were later completely normal
- the direct
.hf.space URL worked
- another user reported the same issue in the same thread
- the author says they did nothing else and it “suddenly worked.” (Hugging Face Forums)
That 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)
What was probably not the main cause
Not a slow-start timeout
Hugging 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)
Probably not a broken Docker launch command
The 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)
The most likely root-cause picture
The cleanest explanation is this:
- Primary app-side issue: root
HEAD requests were not handled correctly, producing 405 instead of 200.
- 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)
So 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)
Solutions for this Space
1. Keep the explicit @app.head('/') handler
This 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)
2. Add lightweight /healthz and /readyz endpoints
Right 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:
/healthz: returns 200 immediately if the web process is alive/readyz: returns whether the model/data layer is actually ready. (Hugging Face)
3. Keep Docker wiring aligned exactly as it is
For 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)
4. Only use startup_duration_timeout if startup later becomes genuinely slow
If 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)
Practical debugging checklist for the next time this happens
If this Space gets stuck on Starting again, the fastest checks are:
curl -I https://huggingface.co/proxy/sakizuki-danboorusearch.hf.space/
If this fails or returns 405 again, that is immediately suspicious.- Open the direct
.hf.space URL.
If it works but the Space page still says Starting, the platform status layer is probably lagging reality.
- Compare logs with actual reachability.
If logs look bad but the direct app works, do not assume the app is dead.
- Check lightweight health endpoints once they exist.
That will separate “web server is up” from “engine is ready.” (Hugging Face Forums)
Final answer
For SAkizuki/DanbooruSearch, the best explanation is:
- the app had a real readiness/HTTP compatibility issue at the root path because
HEAD / returned 405, and
- 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)
The 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)