# Streamlit at Huggingface Space issue

**URL:** <https://discuss.huggingface.co/t/streamlit-at-huggingface-space-issue/171519>\
**Category:** Beginners\
**Created:** [December 14, 2025, 1:32pm UTC](https://discuss.huggingface.co/t/streamlit-at-huggingface-space-issue/171519 "2025-12-14T13:32:47Z")\
**Posts on this page:** 1\
**Showing post:** 2

<div class="post-metadata">

**Author:** ![John6666](https://sea2.discourse-cdn.com/hellohellohello/user_avatar/discuss.huggingface.co/john6666/32/27664_2.png) [@John6666](https://discuss.huggingface.co/u/John6666)\
**Post date:** [December 14, 2025, 2:20pm UTC](https://discuss.huggingface.co/t/streamlit-at-huggingface-space-issue/171519/2 "2025-12-14T14:20:46Z")

</div>

There are several known potential causes.

* * *

Your screenshot is not “Streamlit crashed.” It is “the browser loaded an HTML shell that references hashed Streamlit assets, but those assets 404, so the page stays white.”

You can see it directly in the DevTools console:

- `GET .../static/js/index.<hash>.js` → **404**
- `GET .../static/css/index.<hash>.css` → **404**
- `GET .../static/media/SourceSans...woff2` → **404**

If the JS bundle does not load, Streamlit cannot render anything. White screen is the expected result.

* * *

## Causes ranked for your exact symptom

### 1) Stale cached `index.html` referencing old hashed assets (most common)

Streamlit’s frontend uses hashed filenames. After a rebuild the hash changes. If your browser (or an intermediate cache) still serves an older `index.html`, it will request old `/static/...<oldhash>...` files that no longer exist. That produces exactly what you see: a blank page plus 404s for the hashed assets.

This exact “updated Streamlit Space → blank/404 assets → logs look fine” pattern has been reported on HF, and clearing cache fixed it. ([Hugging Face Forums](https://discuss.huggingface.co/t/updated-my-streamlit-space-now-get-an-error/36637 "Updated My Streamlit Space, now get an error"))

**Fix**

- Open the **direct** Space URL on `*.hf.space` (not just the `huggingface.co/spaces/...` embed).
- Chrome DevTools → Network → enable **Disable cache** → hard reload.
- Try Incognito.
- Clear site data for the `*.hf.space` domain.

**How to confirm**

- If Incognito works but normal mode fails, it is caching. No code change needed.

* * *

### 2) Port mismatch (Docker Space): HF proxies 7860, Streamlit listens on 8501

If you are using **Docker Spaces** , HF defaults the exposed app port to **7860** unless you set `app_port:` in the README YAML. ([Hugging Face](https://huggingface.co/docs/hub/en/spaces-sdks-docker "Docker Spaces"))  
Streamlit defaults to **8501**. If HF is routing or health-checking the wrong port, you can get “Space running but web UI broken” behavior, especially when combined with partial caching.

HF maintainers regularly point to missing `app_port: 8501` as the fix for Docker+Streamlit Spaces. ([Hugging Face Forums](https://discuss.huggingface.co/t/debugging-spaceses-application/71242 "Debugging Spaceses Application - Spaces"))

**Fix**

- If `sdk: docker`, add to `README.md` YAML:

- Ensure Streamlit binds to all interfaces:

**How to confirm**

- In the container, `curl -I http://127.0.0.1:8501/` returns 200.
- Public UI starts working after setting `app_port`.

* * *

### 3) Streamlit SDK Space: you overrode the port away from 8501

If you are using HF’s **Streamlit SDK Space** (not Docker), HF states **only port 8501 is allowed** and warns not to override it in `.streamlit/config.toml`. ([Hugging Face](https://huggingface.co/docs/hub/en/spaces-sdks-streamlit "Streamlit Spaces"))

**Fix**

- Remove any `port = ...` override in `.streamlit/config.toml`.
- Do not try to run Streamlit on 7860 in Streamlit SDK mode.

* * *

### 4) Reverse-proxy base path or trailing-slash routing (common elsewhere, less likely on HF root)

Your symptom (blank page + 404 JS/CSS) is also what Streamlit looks like behind a proxy when the URL path is not what Streamlit expects. Examples:

- “Blank page, title Streamlit, 404 JS/CSS” after deployment behind ingress/proxy. ([Streamlit](https://discuss.streamlit.io/t/blank-page-after-deployment-on-eks-cluster/21726 "Blank Page After Deployment on EKS cluster"))
- Streamlit behind reverse proxy can break if the trailing slash behavior is wrong. ([GitHub](https://github.com/streamlit/streamlit/issues/1139 "Streamlit does not work correctly behind a reverse proxy if ..."))
- If serving under a prefix, you may need `server.baseUrlPath`. ([Streamlit](https://discuss.streamlit.io/t/modify-base-rout-root-path-in-streamlit/31370 "Modify base rout (root path) in Streamlit - Deployment"))

On HF, most apps are served at `/` on `*.hf.space`, so this is usually not the first suspect. It becomes relevant if you added your own proxy layer inside Docker (nginx, FastAPI mount, etc.).

* * *

### 5) Docker user / permissions pitfalls (relevant if you customized the runtime user)

This does not usually create “404 for Streamlit’s own hashed assets,” but it often causes “it runs locally, behaves oddly on Spaces,” and it can break builds or runtime file writes.

Your note captures the key points:

- HF Docker Spaces want the runtime to be **UID 1000** , and `/app` owned by that UID for Dev Mode stability.
- Setting `ENV USER=blazor` does not create an OS user, so `COPY --chown=blazor` can fail if the user does not exist.
- Safer pattern is numeric ownership: `COPY --chown=1000:1000 ...`

If you did any user renaming, simplify to UID 1000 + numeric `--chown` until the UI is stable.

* * *

## Debugging playbook that converges quickly

### Step 0: Identify your Space type in `README.md`

Look at the YAML header:

- `sdk: streamlit` → Streamlit SDK rules apply, port 8501 only. ([Hugging Face](https://huggingface.co/docs/hub/en/spaces-sdks-streamlit "Streamlit Spaces"))
- `sdk: docker` → Docker port rules apply, default port 7860 unless `app_port` is set. ([Hugging Face](https://huggingface.co/docs/hub/en/spaces-sdks-docker "Docker Spaces"))

This one step determines which fixes are even relevant.

* * *

### Step 1: Prove or eliminate caching in 60 seconds

1. Open `https://<space>.hf.space/` directly (not just the Hub page embed).
2. Incognito.
3. DevTools Network tab → **Disable cache** → reload.

If that fixes it, stop. It was stale cached HTML referencing old hashed assets. HF users have reported this exact fix. ([Hugging Face Forums](https://discuss.huggingface.co/t/updated-my-streamlit-space-now-get-an-error/36637 "Updated My Streamlit Space, now get an error"))

Extra confirmation:

- Right-click → View page source.

- Find the referenced `index.<hash>.js`.

- Paste that exact URL into the address bar.

* * *

### Step 2: If Docker, validate the port end-to-end

HF Docker docs: default exposed port is 7860 and you can change it with `app_port`. ([Hugging Face](https://huggingface.co/docs/hub/en/spaces-sdks-docker "Docker Spaces"))

Inside Dev Mode terminal:

- Check listening ports: `ss -lntp | egrep '(:7860|:8501)\b'`

- Test locally:

Then ensure README YAML matches the port you confirmed:

- If Streamlit listens on 8501, set `app_port: 8501`. ([Hugging Face](https://huggingface.co/docs/hub/en/spaces-sdks-docker "Docker Spaces"))

HF forum staff explicitly ask “are you missing `app_port: 8501`?” in Docker debugging threads. ([Hugging Face Forums](https://discuss.huggingface.co/t/debugging-spaceses-application/71242 "Debugging Spaceses Application - Spaces"))

* * *

### Step 3: If Streamlit SDK, remove port overrides

HF Streamlit SDK docs: only port 8501 allowed. Do not override in `config.toml`. ([Hugging Face](https://huggingface.co/docs/hub/en/spaces-sdks-streamlit "Streamlit Spaces"))

Check `.streamlit/config.toml` and remove:

- `[server] port = ...` (unless it is 8501)

Streamlit’s own `config.toml` docs show where this file is picked up and how it is applied. ([StreamlitDocument](https://docs.streamlit.io/develop/api-reference/configuration/config.toml "config.toml - Streamlit Docs"))

* * *

### Step 4: Use Dev Mode properly (you already enabled it)

Dev Mode gives you SSH and VS Code into the running container and lets you restart the app quickly. ([Hugging Face](https://huggingface.co/docs/hub/en/spaces-dev-mode "Spaces Dev Mode: Seamless development in Spaces"))  
Use it to:

- inspect ports
- curl localhost endpoints
- compare what the container serves vs what the browser requests

* * *

## Common “next problem” after the white screen: uploads fail with 403

Once your UI loads, file upload often fails on Spaces because cookies are restricted in the embedded context. HF documents disabling Streamlit XSRF protection as the workaround. ([Hugging Face](https://huggingface.co/docs/hub/en/spaces-cookie-limitations "Cookie limitations in Spaces"))

Not your current 404 symptom, but highly likely to come next if you use `st.file_uploader()`.

* * *

## Summary

- Your screenshot matches “hashed Streamlit static assets 404.” That usually means stale cached HTML. Clearing cache has fixed the same symptom on HF. ([Hugging Face Forums](https://discuss.huggingface.co/t/updated-my-streamlit-space-now-get-an-error/36637 "Updated My Streamlit Space, now get an error"))
- If you are on Docker, verify Streamlit port vs `app_port` (7860 vs 8501). HF docs and staff examples point to `app_port: 8501` as the common fix. ([Hugging Face](https://huggingface.co/docs/hub/en/spaces-sdks-docker "Docker Spaces"))
- If you are on Streamlit SDK, do not override the port away from 8501. ([Hugging Face](https://huggingface.co/docs/hub/en/spaces-sdks-streamlit "Streamlit Spaces"))
- Use Dev Mode to `ss` and `curl` localhost endpoints and prove what the container is serving. ([Hugging Face](https://huggingface.co/docs/hub/en/spaces-dev-mode "Spaces Dev Mode: Seamless development in Spaces"))
- If you changed Docker users, keep UID 1000 and use numeric `--chown=1000:1000` until stable.

---

_[View the full topic](https://discuss.huggingface.co/t/streamlit-at-huggingface-space-issue/171519)._