reflex-dev/reflex · error · SystemExit

Failed to unzip the template: {uze}

Error message

Failed to unzip the template: {uze}

What it means

Raised by `create_config_init_app_from_remote_template` when `zipfile.ZipFile(zip_file_path).extractall(unzip_dir)` throws any exception: the downloaded file is not a valid zip (BadZipFile), individual member IO fails, or paths are inaccessible. The generic `except Exception` catches all unzip failures and exits.

Source

Thrown at reflex/utils/templates.py:164

        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.
    except Exception as uze:
        logger.error(f"Failed to unzip the template: {uze}")
        raise SystemExit(1) from None

    if len(subdirs := list(unzip_dir.iterdir())) != 1:
        logger.error(f"Expected one directory in the zip, found {subdirs}")
        raise SystemExit(1)

    template_dir = unzip_dir / subdirs[0]
    logger.debug(f"Template folder is located at {template_dir}")

    # Move the rxconfig file here first.
    path_ops.mv(str(template_dir / constants.Config.FILE), constants.Config.FILE)
    new_config = reload_config()

    # Get the template app's name from rxconfig in case it is different than
    # the source code repo name on github.
    template_name = new_config.app_name

    # Rewrite in place instead of regenerating from a stock template, so the
    # template's own config (db_url, redis_url, plugins, etc.) is preserved.

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Verify the URL is the direct zip archive link (e.g. https://codeload.github.com/.../zip/refs/heads/main), not an HTML page.
2. Download the URL manually (curl -L -o t.zip && unzip -t t.zip) to confirm it's a valid zip.
3. If the download was truncated by a proxy, retry on an unrestricted network.

import zipfile, tempfile, urllib.request

def zip_is_valid(url: str) -> bool:
    try:
        with tempfile.NamedTemporaryFile(suffix=".zip") as f:
            urllib.request.urlretrieve(url, f.name)
            return zipfile.ZipFile(f.name).testzip() is None
    except Exception:
        return False

try:
    create_config_init_app_from_remote_template(...)
except SystemExit:
    # reflex logged 'Failed to unzip'; verify the URL serves a real zip
    # and fall back to the default template
    initialize_default_app(...)

When it happens

Trigger: The template URL returned an HTML error page or redirect body instead of a zip (BadZipFile); a truncated download; zip members with paths that can't be created; encoding issues in member names.

Common situations: Template URL pointing at a GitHub HTML page instead of the codeload archive endpoint; a proxy returning an error page with 200; interrupted download leaving a partial file.

Related errors

• Expected one directory in the zip, found {subdirs}
• Only {template_name=} should be provided, got {template_code
• For `{template_name}` template, `template_code_dir_name` and
• Failed to create temp directory for download: {ose}
• Failed to download the template: {he}

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