dagger/dagger · critical · DownloadError

Downloaded CLI binary checksum ({actual_hash}) does not matc

Error message

Downloaded CLI binary checksum ({actual_hash}) does not match expected checksum ({expected_hash})

What it means

DownloadError raised when the SHA256 hash of the downloaded dagger CLI binary does not match the checksum published in the release checksums file. The library treats this as evidence of corruption or tampering and refuses to use the binary.

Source

Thrown at sdk/python/src/dagger/provisioning/_download.py:211

        except httpx.HTTPError as e:
            msg = f"Failed to download checksums from {self.checksum_url}: {e}"
            raise DownloadError(msg) from e

        self.progress.update_sync("Downloading dagger CLI")

        with TempFile(f"temp-{self.CLI_BIN_PREFIX}", self.cache_dir) as tmp_bin:
            try:
                actual_hash = self.extract_cli_archive(tmp_bin)
            except httpx.HTTPError as e:
                msg = f"Failed to download archive from {self.archive_url}: {e}"
                raise DownloadError(msg) from e

            if actual_hash != expected_hash:
                msg = (
                    f"Downloaded CLI binary checksum ({actual_hash}) "
                    f"does not match expected checksum ({expected_hash})"
                )
                raise DownloadError(msg)

        tmp_bin_path = Path(tmp_bin.name)
        tmp_bin_path.chmod(0o700)
        return tmp_bin_path.rename(path)

    def expected_checksum(self) -> str:
        archive_name = self.archive_name
        with httpx.stream("GET", self.checksum_url, follow_redirects=True) as r:
            try:
                r.raise_for_status()
            except httpx.HTTPStatusError as e:
                if self.is_cli_release_unavailable(e.response.status_code):
                    msg = f"Failed to download checksums from {self.checksum_url}: {e}"
                    raise CLIReleaseUnavailableError(msg) from e
                raise
            for line in r.iter_lines():
                checksum, filename = line.split()
                if filename == archive_name:

View on GitHub (pinned to 82ba2681db)

Solutions

Delete the provisioning cache directory (dagger's cache_dir holding temp downloads) and retry.
Retry the download — a fresh attempt usually produces a matching checksum.
Check for TLS-intercepting proxies/AV software modifying binary downloads and add an exclusion.
Verify you are on an official build; if pinning a custom version, ensure the checksums file matches your archive.
Pre-install a verified dagger CLI on PATH to skip download verification entirely.

Defensive patterns

Strategy: retry

Validate before calling

# clear corrupted cache before running
cache = Path.home() / ".cache" / "dagger"  # adjust to your platform cache dir
if cache.exists() and not all((cache).glob("cli-*")):
    shutil.rmtree(cache, ignore_errors=True)

Try / catch

from dagger.provisioning import DownloadError
try:
    async with dagger.Connection() as client:
        ...
except DownloadError as e:
    if "checksum" in str(e):
        clear_download_cache()  # purge and re-download
        raise

Prevention

Never disable or proxy TLS to dl.dagger.io (no MITM inspection of binaries).
Exclude the dagger cache dir from AV/quota-affected disks.
Verify available disk space before provisioning.
Install the CLI from a trusted package manager instead of runtime download in sensitive environments.

When it happens

Trigger: _download compares actual_hash (hash of extracted CLI) against expected_checksum(); any mismatch raises. Caused by corrupted downloads, disk issues, or a tampered/mirror-substituted binary.

Common situations: Interrupted download that still passed streaming; MITM proxies re-writing content; caching proxies serving stale/partial archives; corrupted cache_dir contents on disk.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

AI-assisted analysis of dagger/dagger@82ba2681db (2026-09-05). Data as JSON: /api/errors/12b4b579549badee. Report an issue: GitHub.