HF Space "Static SDK is not supported"

Spaces
2

That probably won’t be a problem…

Sometimes the cache causes issues; in those cases, you can clear it by making a meaningless change to the sdk: line and then reverting it…

Is it a problem that you don’t have app_build_command?

No.

Static Spaces can work in either of these modes:

  1. You commit the built files (e.g., dist/) and set app_file to the HTML entrypoint.
  2. Hugging Face builds for you by running app_build_command on every update and then serving the output from a special build ref (refs/convert/build). (Hugging Face)

So missing app_build_command is only a problem if dist/index.html is not present (or not where app_file points) in the repo revision the Space is serving.

Why it “worked at first” and then later changed to “Static SDK is not supported”

That message is a configuration-level failure. In practice it usually comes from one of these:

1) Your README config is not being parsed as Spaces configuration (very common)

Spaces only read settings from the YAML front-matter block at the very top of README.md. (Hugging Face)

If you literally added:

sdk: static
app_file: dist/index.html

…but not inside a top-of-file YAML front-matter block, Hugging Face may ignore it and fall back into a “configuration error” state.

What “correct” looks like:

---
sdk: static
app_file: dist/index.html
---

Pitfalls that break parsing

  • The YAML block is not the first thing in the README (badges/text above it).
  • It’s inside a Markdown code fence (```).
  • It contains placeholders or invalid YAML.
  • It was edited later and became malformed.

There are public examples where a misconfigured/template README ends up showing the same “Static SDK is not supported” configuration error page. (Hugging Face)

Why the delay?

  • The Space can appear fine until a rebuild/restart causes Hugging Face to re-evaluate config strictly, or until a platform-side validation change takes effect.

2) Your Space is still set to ZeroGPU from the old Gradio setup

ZeroGPU has a hard constraint: ZeroGPU Spaces are exclusively compatible with the Gradio SDK, not static. (Hugging Face)

Why the delay?

  • It might run briefly (or show cached content), then once the runtime config is enforced/rebuilt it flips into an error state.

Fix

  • Space Settings → Hardware: switch away from ZeroGPU to a CPU tier (or standard GPU where applicable), then rebuild.

3) Dev Mode is enabled

Dev Mode is not available for static Spaces. (Hugging Face)

Fix

  • Space Settings → Dev Mode: disable, then rebuild.

4) app_file path format/validation changed (edge case)

A recent “it randomly stopped working” case was caused by app_file syntax being slightly off and fixed by changing ./index.html → index.html. (Hugging Face Forums)

Your dist/index.html form is the recommended pattern in the docs, but it’s worth verifying you didn’t accidentally use a leading ./ or / in the actual README. (Hugging Face)

5) dist/ is missing (or stale) in the revision being served

If you don’t use app_build_command, Hugging Face serves whatever is committed. If dist/index.html isn’t present (or you pushed a commit without rebuilding locally), you can land in a broken state.

Fix

  • In the Space “Files” view, confirm dist/index.html exists on the current commit and matches app_file.

What I would do for your case (fastest path)

Step 1 — Make the README config unquestionably valid

Put this as the first lines of README.md (no text above it):

---
sdk: static
app_file: dist/index.html
---

This is required because Spaces configuration is read from the README YAML block. (Hugging Face)

Step 2 — Check Settings for static-incompatible modes

Step 3 — Verify the entrypoint exists

Confirm the repository (current commit) contains: dist/index.html and that it loads without needing server-side routing.

“Should we add app_build_command anyway?”

It’s optional, but often improves reliability for teams because it prevents “forgot to commit dist” and makes deploys reproducible.

Static docs describe this build mode: Hugging Face runs your build command on each update and serves the output from refs/convert/build. (Hugging Face)

A typical config:

---
sdk: static
app_build_command: npm ci && npm run build
app_file: dist/index.html
---

(You can use bun, but the most predictable path is using the toolchain Hugging Face documents directly—npm run build—unless you’ve verified bun availability in the build environment.) (Hugging Face)

Quick checklist mapping to your symptoms

  • You pasted config without --- front-matter → very likely cause. (Hugging Face)
  • Space previously used ZeroGPU with Gradio → likely cause. (Hugging Face)
  • Dev Mode enabled during debugging → likely cause. (Hugging Face)
  • app_file format subtly changed (./…) → possible. (Hugging Face Forums)