arduino/Arduino · error · Exception

CRC doesn't match, file is corrupted. It may be a temporary

Error message

CRC doesn't match, file is corrupted. It may be a temporary problem, please retry later.

What it means

During download(), the downloader verifies the checksum (CRC) of the downloaded file each iteration. When the checksum does not match after a resumed/retried download, it deletes the file and throws this Exception, indicating the transfer is corrupt and likely transient.

Source

Thrown at arduino-core/src/cc/arduino/contributions/DownloadableContributionsDownloader.java:101

      // Test checksum
      progress.setStatus(tr("Verifying archive integrity..."));
      progressListener.onProgress(progress);
      if (hasChecksum(contribution)) {
        String checksum = contribution.getChecksum();
        String algo = checksum.split(":")[0];
        String crc = FileHash.hash(outputFile.toFile(), algo);
        if (!crc.equalsIgnoreCase(checksum)) {
          // If the file has not been downloaded it may be a leftover of
          // a previous download that failed. In this case delete it and
          // try to download it again.
          if (!downloaded) {
            Files.delete(outputFile);
            downloaded = true; // Redundant to avoid loops in case delete fails
            continue;
          }

          // Otherwise throw the error.
          throw new Exception(tr("CRC doesn't match, file is corrupted. It may be a temporary problem, please retry later."));
        }
      }

      // Download completed successfully
      break;
    }

    contribution.setDownloaded(true);
    contribution.setDownloadedFile(outputFile.toFile());
    return outputFile.toFile();
  }

  private boolean hasChecksum(DownloadableContribution contribution) {
    String checksum = contribution.getChecksum();
    if (checksum == null || checksum.isEmpty()) {
      return false;
    }

View on GitHub (pinned to a0df6e0e83)

Solutions

Simply retry the download later — the message itself says the corruption is often temporary.
Delete the partially downloaded file from the staging folder and re-run the install/update so a fresh download starts.
Disable resume (call with noResume=true) to force a clean full download.
Check for a proxy/VPN/antivirus intercepting traffic and try a different network; verify the index checksum matches the published package.

Defensive patterns

Strategy: retry

Try / catch

try { downloader.download(c, progress, status, listener, false, true); } catch (Exception e) { if (e.getMessage().startsWith("CRC doesn't match")) { deletePartialFile(c); retryWithNoResume(c); } else { throw e; } }

Prevention

Use a stable network connection for large package downloads.
Disable download resume when resuming is suspected of causing corruption.
Verify staging folder contents after interrupted downloads.

When it happens

Trigger: download() completes a transfer (possibly after resume attempts) whose computed checksum does not match contribution.getChecksum(); the code deletes the bad file and throws.

Common situations: Unstable network connections or interrupted downloads producing partial/corrupt archives; a resumed download resuming from a stale offset; proxy or antivirus mangling the payload; the published checksum on the index changed while an old cached file remains.

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 arduino/Arduino@a0df6e0e83 (2026-09-06). Data as JSON: /api/errors/5d4f0ffa77163433. Report an issue: GitHub.