Diagnose and recover failing or stuck Hugging Face Space deployments for OpenEnv environments. Use when deploying envs from `envs/` to the Hub (`openenv` namespace with version suffixes), when Spaces are in `BUILDING`/`APP_STARTING`/`RUNTIME_ERROR`, or when release collections need to be reconciled after targeted redeploys.
Use this skill to recover OpenEnv Hub deployments quickly with minimal blast radius.
Use a single release tuple across all commands:
openenvvX.Y.Z-vX-Y-ZDefault to a version suffix and treat unsuffixed Spaces as legacy.
Collect all versioned spaces and isolate non-running ones:
hf spaces ls --author openenv --limit 500 --expand=runtime \
| jq -r '.[] | select(.id|test("-v[0-9]+-[0-9]+-[0-9]+$")) \
| [.id, .runtime.stage, (.runtime.raw.errorMessage // "")] | @tsv' \
| sort
Treat RUNNING and SLEEPING as healthy. Triage everything else.
RUNTIME_ERROR: read traceback from .runtime.raw.errorMessage.BUILD_ERROR: read build error text from runtime info, then patch Dockerfile/deps.APP_STARTING longer than 10 minutes: inspect event stream and metrics before changing code.hf spaces info openenv/<space-id> --expand=runtime
curl -sS -m 10 https://huggingface.co/api/spaces/openenv/<space-id>/events | sed -n '1,140p'
curl -sS -m 10 -i https://huggingface.co/api/spaces/openenv/<space-id>/metrics | sed -n '1,120p'
Read references/troubleshooting.md for symptom-to-fix mappings.
Prefer targeted redeploys over full-fleet pushes:
scripts/prepare_hf_deployment.sh \
--hf-namespace openenv \
--env <env_name> \
--skip-collection
Use openenv CLI as a supplement, not a replacement, for release triage:
uv run openenv validate ...) when applicable.scripts/prepare_hf_deployment.sh to preserve suffix/pinning behavior.If Space remains in APP_STARTING with no actionable error:
uv run --with huggingface_hub python - <<'PY'
from huggingface_hub import HfApi
api = HfApi()
api.restart_space("openenv/<space-id>", factory_reboot=True)
PY
If still stuck, force recreation as last resort:
hf repo delete openenv/<space-id> --repo-type space
scripts/prepare_hf_deployment.sh --hf-namespace openenv --env <env_name> --skip-collection
Verify both runtime stage and health endpoint:
hf spaces info openenv/<space-id> --expand=runtime
curl -sS -m 10 https://<space-subdomain>.hf.space/health
Then verify fleet-wide:
hf spaces ls --author openenv --limit 500 --expand=runtime \
| jq -r '.[] | select(.id|test("-v[0-9]+-[0-9]+-[0-9]+$")) \
| select(.runtime.stage!="RUNNING" and .runtime.stage!="SLEEPING") \
| [.id, .runtime.stage] | @tsv' | sort
When targeted deploys are done, update collection membership for the same version:
python3 scripts/manage_hf_collection.py \
--version vX.Y.Z \
--collection-namespace openenv \
--space-id openenv/<space-id>
Add one --space-id per redeployed space.