{"record":{"id":"99eb22f3e3bbaa10","repo":"roboflow/supervision","slug":"downloaded-asset-filename-failed-md5-verificatio","errorCode":null,"errorMessage":"Downloaded asset {filename} failed MD5 verification.","messagePattern":"Downloaded asset (.+?) failed MD5 verification\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/assets/downloader.py","lineNumber":71,"sourceCode":"    _download_asset(filename, destination)\n\n    if is_md5_hash_matching(check_target, original_md5_hash):\n        return\n\n    logger.warning(\"File corrupted. Re-downloading...\")\n    os.remove(check_target)\n\n    if retry_on_mismatch:\n        _download_verified_asset(\n            filename=filename,\n            original_md5_hash=original_md5_hash,\n            destination=destination,\n            check_target=check_target,\n            retry_on_mismatch=False,\n        )\n        return\n\n    raise ValueError(f\"Downloaded asset {filename!r} failed MD5 verification.\")\n\n\ndef download_assets(\n    asset_name: Assets | str,\n    directory: str | Path | None = None,\n) -> str:\n    \"\"\"\n    Download a specified asset if it doesn't already exist or is corrupted.\n\n    Args:\n        asset_name: The name or type of the asset to be downloaded.\n        directory: Optional output directory. Defaults to the current working\n            directory for backward compatibility.\n\n    Returns:\n        The downloaded asset path. When `directory` is omitted, this preserves\n        the historical filename-only return value.\n","sourceCodeStart":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/assets/downloader.py#L53-L89","documentation":"Raised by the supervision asset downloader when a downloaded file's MD5 hash does not match the expected hash recorded in MEDIA_ASSETS, after one automatic retry. This protects against corrupted or truncated downloads (flaky networks, interrupted connections) so downstream code never consumes a broken asset.","triggerScenarios":"Calling download_assets(...) where the download completes but the file bytes hash differently — e.g. a proxy injecting an error page, a partially-written file, or a host whose mirror serves modified content. Note the downloader retries once (retry_on_mismatch) before raising.","commonSituations":"CI runners behind corporate proxies that alter responses; interrupted connections on slow networks; disk full causing truncated writes; the asset URL being repointed to different content.","solutions":["Delete the partially downloaded file in the target directory and call download_assets() again fresh.","Check network/proxy environment (HTTP_PROXY/HTTPS_PROXY) — ensure nothing is rewriting the response body.","Verify the destination directory is writable and has disk space.","If it persists, download the asset manually and place it at the expected path with the correct name."],"exampleFix":"// before\ndownload_assets(Assets.ENCODED_VIDEO, directory=\"assets\")  # MD5 mismatch\n\n// after\n# clear the corrupted file, then re-download\nif (Path(\"assets\") / \"cctv-1080p.mp4\").exists():\n    (Path(\"assets\") / \"cctv-1080p.mp4\").unlink()\ndownload_assets(Assets.ENCODED_VIDEO, directory=\"assets\")","handlingStrategy":"retry","validationCode":"target = Path(directory or \".\") / filename\nif target.exists():\n    target.unlink()  # clear corrupted partial download\npath = download_assets(asset, directory=directory)","typeGuard":null,"tryCatchPattern":"for attempt in range(3):\n    try:\n        path = download_assets(asset, directory=directory)\n        break\n    except ValueError as e:\n        if \"MD5 verification\" not in str(e) or attempt == 2:\n            raise\n        for f in Path(directory).glob(\"*\"):\n            f.unlink()  # remove corrupt files before retrying","preventionTips":["Cache assets once in CI (a persisted directory) instead of downloading every run.","Verify network/proxy settings when downloads repeatedly fail MD5 — a rewriting proxy is the usual cause.","Delete partial files in the destination before re-running after an interrupted download."],"tags":["assets","download","md5","network","integrity"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}