abiosoft/colima · error

error finalizing download: %w

Error message

error finalizing download: %w

What it means

The download finished and passed validation, but the final os.Rename of <sha256-of-url>.downloading to the cache filename failed. Both names live in the same directory, so this is a local rename; typical causes are a non-writable caches directory (the existing .downloading partial is reused for resume, so earlier create checks are skipped), the partial vanishing mid-run, or a destination created by a concurrent process.

Source

Thrown at util/downloader/download.go:141

		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 {
	_, err := os.Stat(CacheFilename(url))
	return err == nil
}

View on GitHub (pinned to c3a5f9184d)

Solutions

1. Clear the cached entry (final filename and .downloading suffix) and retry
2. Fix ownership and permissions of the caches directory so the current user can create and replace files
3. Avoid concurrent downloads sharing one cache dir
4. Read the wrapped error: EACCES/EPERM means perms, ENOENT means a concurrent cleanup raced you

Example fix

// before
if _, err := downloader.Download(host, req); err != nil {
    return err
}
// after: on finalize failure, drop stale entries and retry once
cache := downloader.CacheFilename(req.URL)
cacheFile, err := downloader.Download(host, req)
if err != nil && strings.Contains(err.Error(), "error finalizing download") {
    _ = os.Remove(cache)
    _ = os.Remove(cache + ".downloading")
    cacheFile, err = downloader.Download(host, req)
}
if err != nil {
    return err
}

cache := downloader.CacheFilename(req.URL)
if fi, err := os.Stat(cache); err == nil && !fi.IsDir() {
    if err := os.Remove(cache); err != nil {
        return fmt.Errorf("cannot clear stale cache entry: %w", err)
    }
}

cache := downloader.CacheFilename(req.URL)
cacheFile, err := downloader.Download(host, req)
if err != nil && strings.Contains(err.Error(), "error finalizing download") {
    _ = os.Remove(cache)
    _ = os.Remove(cache + ".downloading")
    cacheFile, err = downloader.Download(host, req)
}
if err != nil {
    return err
}

When it happens

Trigger: The caches directory exists (MkdirAll no-ops) but is not writable for the current user; a stale root-owned .downloading partial is resumed and then the rename into place fails with EACCES; another colima process or cache cleaner removed the partial between download and rename (ENOENT).

Common situations: Mixing sudo and non-sudo colima runs leaving root-owned cache files; two instances downloading the same URL concurrently; antivirus/file watchers briefly locking files on macOS.

Related errors

• error during prune: %w
• error preparing cache dir: %w
• error persisting runtime settings: %w
• error persisting kubernetes settings: %w
• error deleting configs: %w

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