sgl-project/sglang · error · FileNotFoundError

Failed to download Real-ESRGAN weights from HuggingFace repo

Error message

Failed to download Real-ESRGAN weights from HuggingFace repo '{repo_id}' (file: '{filename}'). If you are using a custom model, provide either a local .pth file path or use the 'repo_id:filename' format (e.g. 'my-org/my-esrgan:weights.pth'). Original error: {e}

What it means

FileNotFoundError raised when hf_hub_download fails for the resolved repo_id/filename — network errors, nonexistent repo/file, auth requirements, or rate limits all surface here, chained with the original exception.

Source

Thrown at python/sglang/multimodal_gen/runtime/postprocess/realesrgan_upscaler.py:756

        from huggingface_hub import hf_hub_download
    except ImportError as e:
        raise ImportError(
            "huggingface_hub is required to download Real-ESRGAN weights. "
            "Install it with: pip install huggingface_hub"
        ) from e

    logger.info(
        "Downloading Real-ESRGAN weights from HF repo %s (file: %s)",
        repo_id,
        filename,
    )
    try:
        local_path = hf_hub_download(
            repo_id=repo_id,
            filename=filename,
        )
    except Exception as e:
        raise FileNotFoundError(
            f"Failed to download Real-ESRGAN weights from HuggingFace repo "
            f"'{repo_id}' (file: '{filename}'). If you are using a custom "
            f"model, provide either a local .pth file path or use the "
            f"'repo_id:filename' format (e.g. 'my-org/my-esrgan:weights.pth'). "
            f"Original error: {e}"
        ) from e
    _RESOLVED_MODEL_PATH_CACHE[model_path] = local_path
    return local_path


# ---------------------------------------------------------------------------
# Module-level convenience function
# ---------------------------------------------------------------------------


def upscale_frames(
    frames: list[np.ndarray],
    model_path: Optional[str] = None,

View on GitHub (pinned to 0132848349)

Solutions

1. Use the explicit 'repo_id:filename' format with the exact file name in the repo
2. hf_hub_download the file manually to verify access/auth
3. For offline use, download the .pth and pass a local path

Example fix

# before
model_path = "my-org/my-esrgan"
# after
model_path = "my-org/my-esrgan:weights.pth"

from huggingface_hub import HfApi
files = HfApi().list_repo_files(repo_id)
assert filename in files

try:
    upscaler.upscale(img)
except FileNotFoundError as e:
    if "Failed to download" in str(e):
        upscaler = RealESRGANUpscaler(model_path=LOCAL_FALLBACK_PATH)
    else:
        raise

When it happens

Trigger: model_path like 'my-org/my-esrgan' where the default filename doesn't exist in the repo, or 'repo:filename' pointing at a wrong file name; also offline environments or private repos without a token.

Common situations: Repo renamed/removed; typo in filename; missing HF_TOKEN for gated repos; proxy/firewall blocking huggingface.co.

Related errors

• huggingface_hub is required to download Real-ESRGAN weights.
• Unsupported activation type: {act_type}
• Unsupported RRDBNet conv_first input channels: {in_channels}
• All frames in a batch must have the same resolution
• Failed to load Real-ESRGAN checkpoint from '{resolved_path}'

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/c682eb2e1f29a3c8. Report an issue: GitHub.