abiosoft/colima · error

error validating SHA sum for '%s': %w

Error message

error validating SHA sum for '%s': %w

What it means

The file downloaded successfully but r.SHA.validateDownload failed, so the artifact is not trusted: the .downloading file is renamed to .invalid to force a re-download on the next attempt. The wrapped error is most often *SHAValidationError (digest mismatch), but can also be the unsupported-size error (SHA.Size not 256/512), an open/read failure on the downloaded file, a sha-file fetch/parse failure (errors 273-275), or the 'one of Digest or URL must be set' misuse error.

Source

Thrown at util/downloader/download.go:135

func (d downloader) downloadFile(r Request) (err error) {
	cacheDownloadingFilename := d.cacheDownloadingFileName(r.URL)

	// create cache directory
	cacheDir := filepath.Dir(cacheDownloadingFilename)
	if err := os.MkdirAll(cacheDir, 0755); err != nil {
		return fmt.Errorf("error preparing cache dir: %w", err)
	}

	if err := fileDownloader.Download(r, cacheDownloadingFilename); err != nil {
		return err
	}

	// validate download if SHA is present
	if r.SHA != nil {
		if err := r.SHA.validateDownload(r.URL, cacheDownloadingFilename); err != nil {
			// move file to allow subsequent re-download
			_ = os.Rename(cacheDownloadingFilename, cacheDownloadingFilename+".invalid")
			return fmt.Errorf("error validating SHA sum for '%s': %w", path.Base(r.URL), err)
		}
	}

	// move completed download to final location
	if err := os.Rename(cacheDownloadingFilename, CacheFilename(r.URL)); err != nil {
		return fmt.Errorf("error finalizing download: %w", err)
	}

	return nil
}

func (d downloader) saveResumeInfo(url, etag string, bytesWritten int64) {
	info := ResumeInfo{ETag: etag, BytesWritten: bytesWritten}
	data, _ := json.Marshal(info)
	_ = os.WriteFile(d.resumeInfoPath(url), data, 0644)
}

func (d downloader) hasCache(url string) bool {

View on GitHub (pinned to c3a5f9184d)

Solutions

1. Clear the cached entry (final name plus the .invalid file via downloader.CacheFilename(url)) and retry to force a fresh download
2. Verify manually: shasum -a 256 <file> against the checksum file contents
3. Check SHA.Size is 256 or 512 and that the checksum file actually contains an entry for the artifact basename
4. If upstream's checksum is stale or wrong, report it there; clear local cache after it is fixed

Example fix

// before
cacheFile, err := downloader.Download(host, req)
// after: on SHA failure, clear cache and re-download once
cacheFile, err := downloader.Download(host, req)
if err != nil {
    var shaErr *downloader.SHAValidationError
    if errors.As(err, &shaErr) {
        cache := downloader.CacheFilename(req.URL)
        _ = os.Remove(cache)
        _ = os.Remove(cache + ".invalid")
        cacheFile, err = downloader.Download(host, req)
    }
}
if err != nil {
    return err
}

func isSHAValidation(err error) bool {
    var e *downloader.SHAValidationError
    return errors.As(err, &e) || errors.Is(err, downloader.ErrSHAValidation)
}

cacheFile, err := downloader.Download(host, req)
if err != nil && isSHAValidation(err) {
    cache := downloader.CacheFilename(req.URL)
    _ = os.Remove(cache)
    _ = os.Remove(cache + ".invalid")
    cacheFile, err = downloader.Download(host, req) // one clean re-download
}
if err != nil {
    return err // non-SHA errors and persistent mismatches propagate
}

When it happens

Trigger: Request.SHA is non-nil and validation fails: computed digest differs from the expected one (SHAValidationError); SHA.Size is not 256/512; the checksum URL could not be fetched or parsed; neither SHA.Digest nor SHA.URL was set.

Common situations: Upstream republished the artifact without updating the checksum file (or vice versa); download truncated by a proxy; mirror serves a different file than the checksum source; SHA configured with the wrong Size field.

Related errors

• error preparing cache dir: %w
• cannot create file '%s': %w
• error downloading SHA file from '%s': %w
• error parsing SHA file from '%s': %w
• no SHA entry found for '%s' in checksum file

AI-assisted analysis of abiosoft/colima@c3a5f9184d (2026-08-15). Data as JSON: /api/errors/2f76a428d74da815. Report an issue: GitHub.