reflex-dev/reflex · error · SystemExit

Failed to download the template: {he}

Error message

Failed to download the template: {he}

What it means

Raised by `create_config_init_app_from_remote_template` when the httpx GET that downloads the template zip fails: either a network/transport error or a non-2xx HTTP status (raise_for_status). Any httpx.HTTPError (connect error, timeout, DNS failure, 404/500) triggers this, and the CLI exits with SystemExit(1).

Source

Thrown at reflex/utils/templates.py:143

    import httpx

    # Create a temp directory for the zip download.
    try:
        temp_dir = tempfile.mkdtemp()
    except OSError as ose:
        logger.error(f"Failed to create temp directory for download: {ose}")
        raise SystemExit(1) from None

    # Use httpx GET with redirects to download the zip file.
    zip_file_path: Path = Path(temp_dir) / "template.zip"
    try:
        # Note: following redirects can be risky. We only allow this for reflex built templates at the moment.
        response = net.get(template_url, follow_redirects=True)
        logger.debug(f"Server responded download request: {response}")
        response.raise_for_status()
    except httpx.HTTPError as he:
        logger.error(f"Failed to download the template: {he}")
        raise SystemExit(1) from None
    try:
        zip_file_path.write_bytes(response.content)
        logger.debug(f"Downloaded the zip to {zip_file_path}")
    except OSError as ose:
        logger.error(f"Unable to write the downloaded zip to disk {ose}")
        raise SystemExit(1) from None

    # Create a temp directory for the zip extraction.
    try:
        unzip_dir = Path(tempfile.mkdtemp())
    except OSError as ose:
        logger.error(f"Failed to create temp directory for extracting zip: {ose}")
        raise SystemExit(1) from None

    try:
        zipfile.ZipFile(zip_file_path).extractall(path=unzip_dir)
        # The zip file downloaded from github looks like:
        # repo-name-branch/**/*, so we need to remove the top level directory.

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Verify the template URL is correct and reachable (curl -I <url>).
2. Fix network access: proxy env vars (HTTPS_PROXY), VPN, or retry when connectivity is restored.
3. If the remote template is optional, fall back to the bundled default template (omit the URL).

import httpx

def template_url_ok(url: str) -> bool:
    try:
        r = httpx.head(url, follow_redirects=True, timeout=10)
        return r.status_code == 200
    except httpx.HTTPError:
        return False

for attempt in range(3):
    try:
        create_config_init_app_from_remote_template(...)
        break
    except SystemExit:
        # network failure logged by reflex; back off and retry
        time.sleep(2 ** attempt)
else:
    # fall back to default template
    initialize_default_app(...)

When it happens

Trigger: `reflex init` with a remote template URL while offline, behind a blocking proxy, with a bad URL (404), or when the template host returns 5xx; net.get(template_url, follow_redirects=True) raising httpx.HTTPError.

Common situations: Corporate proxies/firewalls blocking github codeload URLs; typo'd template URL; GitHub outage; flaky CI network; SSL inspection breaking TLS.

Related errors

• The URL argument should start with a /
• Cannot provide both URL and data to download.
• Invalid data type {type(data)} for download. Use `str` or `b
• Cannot use --single-port with --frontend-only or --backend-o
• Cannot specify different ports for frontend and backend when

AI-assisted analysis of reflex-dev/reflex@45b8ed5ab7 (2026-08-28). Data as JSON: /api/errors/d62117bb381d83ab. Report an issue: GitHub.