langchain-ai/deepagents · error · ChecksumMismatchError

Checksum mismatch for

Error message

Checksum mismatch for {path.name}: expected {expected_hex}, got {actual}

What it means

`_verify_sha256` raises `ChecksumMismatchError` when the SHA-256 of the downloaded archive does not match the pinned expected hash. This is an integrity guard against truncated, corrupted, or tampered downloads of managed tools.

Solutions

Delete the cached/corrupt archive and re-download (`rm <archive>` then rerun the install)
Bypass or reconfigure SSL-intercepting proxies so the original bytes arrive
If the upstream release legitimately changed, update the pinned `expected_hex` in the manifest/code to the officially published SHA-256

Example fix

// before
EXPECTED_SHA256["rg-14.1.0.tar.gz"] = "aaaaaaaa..."  # stale pin
// after
$ sha256sum rg-14.1.0.tar.gz
bbbbbbbb...  rg-14.1.0.tar.gz
# update pin to the value published in the upstream release notes
EXPECTED_SHA256["rg-14.1.0.tar.gz"] = "bbbbbbbb..."

Defensive patterns

Strategy: retry

Validate before calling

import hashlib
from pathlib import Path

def matches_pin(archive: Path, expected_hex: str) -> bool:
    h = hashlib.sha256(archive.read_bytes()).hexdigest()
    return h == expected_hex

if not matches_pin(archive, EXPECTED):
    archive.unlink()  # discard corrupt download before retrying

Try / catch

try:
    _install_ripgrep_sync()
except ChecksumMismatchError as exc:
    logger.error("integrity failure: %s", exc)
    raise SystemExit(
        "download corrupted or tampered; remove cache, disable SSL proxy, retry"
    )

Prevention

Never bypass checksum verification; always re-download on mismatch
Check whether a corporate SSL-inspecting proxy rewrites downloads
Update pinned hashes only from the upstream project's official release notes

When it happens

Trigger: `_install_ripgrep_sync` completing a download whose bytes differ from the pinned hash — a truncated download (disk full, connection cut at the end), a proxy injecting content (captive portals, SSL-intercepting middleboxes), or a version mismatch where the code pins a hash for a release that the mirror replaced.

Common situations: Corporate SSL-inspection proxies substituting certificates/content; partial downloads after a network blip; pinned hash lagging a re-tagged upstream release; malicious mirror.

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 langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/7704ccbda68a1371. Report an issue: GitHub.

Appendix: source

Thrown at libs/code/deepagents_code/managed_tools.py:599

    with path.open("rb") as fh:
        for chunk in iter(lambda: fh.read(1 << 20), b""):
            digest.update(chunk)
    return digest.hexdigest()


def _verify_sha256(path: Path, expected_hex: str) -> None:
    """Verify `path` matches `expected_hex`.

    Raises:
        ChecksumMismatchError: When the SHA-256 of `path` differs from
            `expected_hex`.
    """
    actual = _sha256(path)
    if actual != expected_hex:
        msg = (
            f"Checksum mismatch for {path.name}: expected {expected_hex}, got {actual}"
        )
        raise ChecksumMismatchError(msg)


def _extract_rg(archive: Path, extract_root: Path) -> Path:
    """Extract `archive` and locate the `rg` binary inside.

    Handles both `.tar.gz` and `.zip` archives. Release archives nest the
    binary under `ripgrep-<ver>-<triple>/`, so we walk the tree to find it
    rather than hard-coding the prefix. Malformed archives or unsafe
    members propagate `tarfile.TarError` / `zipfile.BadZipFile`.

    Returns:
        Absolute path to the extracted `rg` (or `rg.exe`) binary.

    Raises:
        FileNotFoundError: When the archive does not contain an `rg` binary.
    """
    import tarfile
    import zipfile

View on GitHub (pinned to a1af029e6e)