{"record":{"id":"f8195e26286df7d0","repo":"reflex-dev/reflex","slug":"failed-to-unzip-the-template-uze","errorCode":null,"errorMessage":"Failed to unzip the template: {uze}","messagePattern":"Failed to unzip the template: (.+?)","errorType":"exception","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"reflex/utils/templates.py","lineNumber":164,"sourceCode":"        logger.debug(f\"Downloaded the zip to {zip_file_path}\")\n    except OSError as ose:\n        logger.error(f\"Unable to write the downloaded zip to disk {ose}\")\n        raise SystemExit(1) from None\n\n    # Create a temp directory for the zip extraction.\n    try:\n        unzip_dir = Path(tempfile.mkdtemp())\n    except OSError as ose:\n        logger.error(f\"Failed to create temp directory for extracting zip: {ose}\")\n        raise SystemExit(1) from None\n\n    try:\n        zipfile.ZipFile(zip_file_path).extractall(path=unzip_dir)\n        # The zip file downloaded from github looks like:\n        # repo-name-branch/**/*, so we need to remove the top level directory.\n    except Exception as uze:\n        logger.error(f\"Failed to unzip the template: {uze}\")\n        raise SystemExit(1) from None\n\n    if len(subdirs := list(unzip_dir.iterdir())) != 1:\n        logger.error(f\"Expected one directory in the zip, found {subdirs}\")\n        raise SystemExit(1)\n\n    template_dir = unzip_dir / subdirs[0]\n    logger.debug(f\"Template folder is located at {template_dir}\")\n\n    # Move the rxconfig file here first.\n    path_ops.mv(str(template_dir / constants.Config.FILE), constants.Config.FILE)\n    new_config = reload_config()\n\n    # Get the template app's name from rxconfig in case it is different than\n    # the source code repo name on github.\n    template_name = new_config.app_name\n\n    # Rewrite in place instead of regenerating from a stock template, so the\n    # template's own config (db_url, redis_url, plugins, etc.) is preserved.","sourceCodeStart":146,"sourceCodeEnd":182,"githubUrl":"https://github.com/reflex-dev/reflex/blob/45b8ed5ab735f8a56bbb09a42384f030eb0208e7/reflex/utils/templates.py#L146-L182","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the URL is the direct zip archive link (e.g. https://codeload.github.com/.../zip/refs/heads/main), not an HTML page.","Download the URL manually (curl -L -o t.zip && unzip -t t.zip) to confirm it's a valid zip.","If the download was truncated by a proxy, retry on an unrestricted network."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"import zipfile, tempfile, urllib.request\n\ndef zip_is_valid(url: str) -> bool:\n    try:\n        with tempfile.NamedTemporaryFile(suffix=\".zip\") as f:\n            urllib.request.urlretrieve(url, f.name)\n            return zipfile.ZipFile(f.name).testzip() is None\n    except Exception:\n        return False","typeGuard":null,"tryCatchPattern":"try:\n    create_config_init_app_from_remote_template(...)\nexcept SystemExit:\n    # reflex logged 'Failed to unzip'; verify the URL serves a real zip\n    # and fall back to the default template\n    initialize_default_app(...)","preventionTips":["Use direct archive URLs (codeload.github.com) not HTML pages.","Test template URLs with `curl -L -o t.zip && unzip -t t.zip` before automating init."],"tags":["reflex","templates","zip","badzipfile","download-corruption"],"backgroundTag":"invalid-zip-file","analyzedSha":"45b8ed5ab735f8a56bbb09a42384f030eb0208e7","analyzedAt":"2026-08-28T19:25:27.644Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}