skills.rest
meta-pytorch
meta-pytorchOFFICIAL
Explore all skills by this author →
WebsiteGitHub

hf-space-recovery

Diagnose and recover failing Hugging Face Space deployments for OpenEnv environments.

2.5k|432|Updated Oct 1, 2025
Search Tags:#recovery#Troubleshooting#Deployment#spaces#openenv#hugging face#devOps
One-click install
npx skills add https://github.com/meta-pytorch/OpenEnv --skill hf-space-recovery
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: hf-space-recovery
Source: https://github.com/meta-pytorch/OpenEnv/tree/main/.claude/skills/hf-space-recovery
Command: npx skills add https://github.com/meta-pytorch/OpenEnv --skill hf-space-recovery

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires huggingface_hub, and includes references (resource) components.

What problem does it solve?

Hugging Face Spaces hosting OpenEnv environments can get stuck in BUILDING, APP_STARTING, or RUNTIME_ERROR states, and manually triaging dozens of versioned Spaces is slow and error-prone. This Skill provides a structured recovery workflow that isolates failing Spaces, classifies root causes, applies targeted redeploys, and reconciles release collections.

Core Features & Use Cases

  • Fleet Status Snapshot: Lists all versioned Spaces in the openenv namespace and isolates non-running ones using the hf CLI and jq.
  • Symptom-Based Triage: Classifies RUNTIME_ERROR, BUILD_ERROR, and stuck APP_STARTING states, with a troubleshooting reference mapping symptoms like import tracebacks, missing dependencies, and Dockerfile issues to concrete fixes.
  • Targeted Redeploy and Recovery: Redeploys single environments via scripts/prepare_hf_deployment.sh, force-restarts stuck Spaces with factory reboot, and reconciles release collections afterward.
  • Use Case: After a release, several openenv Spaces show RUNTIME_ERROR due to a missing transitive dependency. Use this Skill to identify the affected Spaces, patch the environment Dockerfile, redeploy only those envs, verify health endpoints, and update the release collection.

Quick Start

Ask the agent to check which openenv Hugging Face Spaces for version vX.Y.Z are not running and recover them.

Frequently Asked Questions about hf-space-recovery

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix a Hugging Face Space stuck in APP_STARTING?▼

First inspect the Space's event stream and metrics API to confirm activity. If there is no actionable error, restart the Space with factory_reboot=True via the huggingface_hub HfApi. If it remains stuck, delete and recreate the Space, then redeploy.

How do I find which Hugging Face Spaces are failing?▼

Run hf spaces ls with --expand=runtime and filter with jq for versioned Space IDs whose runtime stage is not RUNNING or SLEEPING. This produces a triage list of failing Spaces with their error messages.

Why does my Space show RUNTIME_ERROR with ModuleNotFoundError?▼

The environment's library imports pull optional or transitive dependencies missing from the Space Dockerfile. Add the missing dependency directly to the environment Dockerfile and redeploy only the affected environment.

Can I redeploy a single OpenEnv environment instead of the full fleet?▼

Yes, run scripts/prepare_hf_deployment.sh with --env <env_name> and --skip-collection to redeploy one environment. Targeted redeploys are preferred over full-fleet pushes to minimize blast radius.

How do I update a Hugging Face collection after redeploying Spaces?▼

Run scripts/manage_hf_collection.py with the release version, collection namespace, and one --space-id argument per redeployed Space. Keep the collection version aligned with the deployed version suffix set.

Related Skills

Explore More Software Engineering Skills→
humandotlearninghumandotlearning

openenv-cli

Automate OpenEnv environment scaffolding, validation, build, and push workflows.

Community
Intermediate
manastalukdarmanastalukdar
1

canary

Poll logs, error rates, and endpoints to verify post-deployment health.

Community
Advanced
luokai25luokai25

hugging-face-paper-publisher

Publish and manage research papers on Hugging Face Hub.

Community
Advanced
DektoraDektora

orchestrate-coding-session

Dispatch parallel coding sessions across beads in isolated worktrees.

Official
Advanced