crewAIInc/crewAI · error · SystemExit

Failed to download template: {e}

Error message

Failed to download template: {e}

What it means

Raised by RemoteTemplateManager._download_zip() when downloading the zipball of a template repo (`{GITHUB_API_BASE}/repos/{GITHUB_ORG}/{repo_name}/zipball`, 60s timeout, redirects followed) fails with any httpx.HTTPError. The CLI aborts the `crewai template add` operation in red and exits 1; nothing is written to disk because download happens before extraction.

Source

Thrown at lib/cli/src/crewai_cli/remote_template/main.py:214

        templates = self._fetch_templates()
        template_names = {t["name"] for t in templates}

        for candidate in candidates:
            if candidate in template_names:
                return candidate

        return None

    def _download_zip(self, repo_name: str) -> bytes:
        """Download the default branch zipball for a repo."""
        url = f"{GITHUB_API_BASE}/repos/{GITHUB_ORG}/{repo_name}/zipball"
        try:
            response = httpx.get(url, follow_redirects=True, timeout=60)
            response.raise_for_status()
        except httpx.HTTPError as e:
            click.secho(f"Failed to download template: {e}", fg="red")
            raise SystemExit(1) from e

        return response.content

    def _extract_zip(self, zip_bytes: bytes, dest: str) -> None:
        """Extract a GitHub zipball into dest, stripping the top-level directory."""
        with zipfile.ZipFile(io.BytesIO(zip_bytes)) as zf:
            # GitHub zipballs have a single top-level dir like 'crewAIInc-fde-template_xxx-<sha>/'
            members = zf.namelist()
            if not members:
                click.secho("Downloaded archive is empty.", fg="red")
                raise SystemExit(1)

            top_dir = members[0].split("/")[0] + "/"

            os.makedirs(dest, exist_ok=True)

            for member in members:
                if member == top_dir or not member.startswith(top_dir):

View on GitHub (pinned to 754d7323be)

Solutions

1. Retry the command — most zipball failures are transient network/TLS issues.
2. If the message shows 404, re-run `crewai template list` to confirm the template still exists.
3. Configure proxy/CA trust (HTTPS_PROXY, SSL_CERT_FILE) in proxy environments.
4. Pre-download the zip manually from https://github.com/crewAIInc/<repo>/archive/refs/heads/main.zip as a workaround and unzip it yourself.

Example fix

# before
$ crewai template add template_deep_research
# Failed to download template: Read timed out. (read timeout=60)

# after
$ crewai template add template_deep_research  # retry on a stable link, or:
$ curl -L -o t.zip https://github.com/crewAIInc/template_deep_research/archive/refs/heads/main.zip && unzip t.zip

import httpx

repo = "template_deep_research"
probe = httpx.head(
    f"https://api.github.com/repos/crewAIInc/{repo}/zipball",
    follow_redirects=True,
    timeout=15,
)
probe.raise_for_status()  # confirms reachability + repo exists before the CLI run

import time

for attempt in range(3):
    try:
        add_template("template_deep_research")
        break
    except SystemExit:
        time.sleep(3 * (attempt + 1))  # transient TLS/timeout: back off
else:
    raise SystemExit("template download failed after retries")

When it happens

Trigger: GET of the zipball endpoint raising: connection reset/timeout for large repos on slow links (60s exceeded), 404 if the repo was deleted between list and add, 403/429 rate limiting, or a proxy stripping the redirect to codeload.github.com (follow_redirects=True requires the redirect to succeed).

Common situations: Slow networks downloading large templates; GitHub rate limits hit because each add re-lists repos then downloads; corporate SSL-inspecting proxies with untrusted CAs causing TLS errors; template removed upstream mid-session.

Related errors

• Failed to fetch templates from GitHub: {e}
• Downloaded archive is empty.
• Error fetching content from URL {url}: {e!s}
• Brave Search API request timed out after {self._timeout}s: {
• Failed to communicate with Agent Handler API: {e!s}

AI-assisted analysis of crewAIInc/crewAI@754d7323be (2026-08-15). Data as JSON: /api/errors/1670a1be2506161d. Report an issue: GitHub.