HF Space "Static SDK is not supported"

Spaces
6

The below long output is purely a general observation.
Personally, when encountering frequent minor yet peculiar errors like this, I’ve found it wise to also consider the possibility that the site is undergoing some changes, causing unstable behavior, or that some incorrect flags are set in the space… (When caused by incorrect flags, the same code often runs without issues in a separately created space. For caching issues, creating a separate space is usually the simplest fix.):thinking:

What that error actually means

On Hugging Face Spaces, “Static SDK is not supported” is a configuration-layer failure, not a “your JS crashed” runtime failure.

It typically appears when the Hub can’t (or won’t) apply sdk: static for that Space, so it falls back to a generic “configuration error” page (the one that shows the “Base README.md template”). You can see the exact same config-error page pattern in other public Spaces, e.g. lmarena-ai/lmarena-leaderboard and victor/sveltekit-space. (Hugging Face)

Is app_build_command required?

No.

Hugging Face supports two “static” modes:

  1. Commit built assets (your approach): you push dist/ and set app_file to the HTML entry point.
  2. Build on Hugging Face: you set app_build_command, and HF runs it on updates, then serves the output. (Hugging Face)

So the absence of app_build_command is only a problem if dist/index.html is missing or wrong.

In your repo, the config is present and correctly formatted as front-matter, and dist/index.html exists. (Hugging Face)

Can you see logs for this kind of failure?

1) Where logs normally are

For “normal” (container-based) Spaces, HF exposes logs via the Logs tab / Logs UI. (Hugging Face Forums)

2) What that means for Static Spaces

A pure static Space does not run an app server, so there are typically:

  • no container runtime logs, because there’s no long-running container
  • only build logs if you use app_build_command (because then HF actually runs a build job) (Hugging Face)

When you’re in Configuration error, you often won’t get meaningful “logs” because the platform is failing before a build/run phase starts.

The most common causes (and fixes)

Cause A — The Space is in a mode that Static doesn’t support (most likely in Gradio→Static migrations)

Two settings are frequent culprits:

A1) ZeroGPU still enabled

HF’s ZeroGPU doc explicitly says: “ZeroGPU Spaces are exclusively compatible with the Gradio SDK.” (Hugging Face)

Fix

  • Space Settings → Hardware
  • Switch away from ZeroGPU to a CPU tier (or dedicated GPU), then rebuild/restart.

A2) Dev Mode enabled

HF Dev Mode doc explicitly says: Dev Mode is not available for static Spaces. (Hugging Face)

Fix

  • Space Settings → Dev Mode
  • Disable it, then rebuild/restart.

Why it “worked for 2 days”
These settings can look fine until a rebuild/restart/validation pass happens (sleep/wake, infra reschedule, manual restart), then the platform enforces the incompatibility and flips to config error.

Cause B — HF is not actually using your README config (YAML parsing / precedence issues)

HF reads Space config from the YAML front-matter block at the very top of README. (Hugging Face)

Common pitfalls:

  • Anything (badges, headings) above the --- block
  • Putting the YAML inside a markdown code fence
  • YAML becoming invalid after an edit

In your current README.md, the front-matter looks correct in the file view. (Hugging Face)
Still, if you edited via UI and introduced invisible formatting issues, it can cause intermittent “config not applied” behavior.

Fix

  • Ensure the README starts exactly like this (first byte of file is the first -):

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

  • Commit a small change to the YAML block (e.g. toggle pinned), push, then revert (forces config re-evaluation).

Cause C — Static build steps may be paywalled in some situations

Hugging Face’s static docs describe app_build_command as supported. (Hugging Face)
However, multiple public Spaces currently show a configuration error stating:

“Static space builds require a paid plan. Subscribe to Team or Enterprise …” (Hugging Face)

So:

  • Static without app_build_command: generally works as simple hosting (your approach).
  • Static with app_build_command: may trigger the paid-plan gate in some accounts/orgs (based on the error HF itself shows). (Hugging Face)

If you add app_build_command just to “get logs”, you might hit that gate.

Workarounds if you need reproducible builds without HF build

  • Build in CI and commit/push dist/ (what you’re doing)
  • HF’s own blog suggests a “two-space” pattern: a Docker “builder” Space that builds and deploys to a static “site” Space. (Hugging Face)

Cause D — Platform-side regression/outage (less common, but real)

When very large/high-profile Spaces also show “Static SDK is not supported”, it can indicate an HF-side regression rather than your repo (example: lmarena-ai/lmarena-leaderboard showing the same configuration error page). (Hugging Face)

What you can do

  • Apply the fixes in A/B first (they’re quick and within your control)

  • If still broken, open a forum thread with:

    • the Space URL
    • a screenshot of Settings → Hardware and Settings → Dev Mode
    • the exact top-of-README YAML block (raw)
    • whether it reproduces on a brand-new static Space under the same org

What I would do for your Space (ordered, fastest signal first)

  1. Check Settings → Hardware
    If it’s ZeroGPU, switch to CPU. (Static + ZeroGPU is incompatible.) (Hugging Face)

  2. Check Settings → Dev Mode
    If enabled, disable it. (Static + Dev Mode is unsupported.) (Hugging Face)

  3. Force a config refresh

    • Make a tiny commit touching the YAML front-matter (e.g., add/remove a space, toggle pinned), then revert.
    • This often clears “stuck” config evaluation after SDK migration.

  4. Do not add app_build_command just for troubleshooting unless you’ve confirmed your org/account won’t hit the “static build requires paid plan” gate. (Hugging Face)

  5. If it still flips back after a day or two:
    Create a brand-new Static HTML Space under the same org and push only a minimal dist/index.html + README front-matter. If that also breaks, it strongly points to org-level restrictions or HF-side behavior, not your app bundle.

Good references and similar cases

  • Official docs

    • Static HTML Spaces + build step (app_build_command) (Hugging Face)
    • Spaces config YAML rules (front-matter at top of README) (Hugging Face)
    • ZeroGPU compatibility (“Gradio-only”) (Hugging Face)
    • Dev Mode limitation (not for static) (Hugging Face)

  • Logs / debugging

  • Similar failures

If you want the single most likely fix given “Gradio → Static” + “works, then breaks after ~2 days”: ZeroGPU or Dev Mode still enabled in Settings (static-incompatible), with the failure surfacing on a rebuild/revalidation. (Hugging Face)