lima-vm/lima · error

local files are not cached

Error message

local files are not cached

What it means

The cache is keyed by the remote URL (by-url-sha256). Local files (paths without a scheme, or file:// URLs) have no remote identity to cache and are documented as not cached, so Cached() rejects them immediately with this error.

Source

Thrown at pkg/downloader/downloader.go:553

	return algo.FromReader(f)
}

// Cached checks if the remote resource is in the cache.
//
// Download caches the remote resource if WithCache or WithCacheDir option is specified.
// Local files are not cached.
//
// When the cache path already exists, Cached returns Result with StatusUsedCache.
func Cached(remote string, opts ...Opt) (*Result, error) {
	var o options
	if err := o.apply(opts); err != nil {
		return nil, err
	}
	if o.cacheDir == "" {
		return nil, errors.New("caching-only mode requires the cache directory to be specified")
	}
	if IsLocal(remote) {
		return nil, errors.New("local files are not cached")
	}

	shad := cacheDirectoryPath(o.cacheDir, remote)
	shadData := filepath.Join(shad, "data")
	shadTime := filepath.Join(shad, "time")
	shadType := filepath.Join(shad, "type")
	shadDigest, err := cacheDigestPath(shad, o.expectedDigest)
	if err != nil {
		return nil, err
	}

	// Checking if data file exists is safe without locking.
	if _, err := os.Stat(shadData); err != nil {
		return nil, err
	}

	// But validating the digest or the data file must take the lock to avoid races
	// with parallel downloads.

View on GitHub (pinned to dd909d0973)

Solutions

1. Only call Cached for http(s)/remote URLs; guard with downloader.IsLocal(remote) first
2. For local files, use Download with the local path (local files are copied, not cached) or handle them directly
3. If testing, serve the file over a local HTTP server so it has a remote URL key

Example fix

// before
res, err := downloader.Cached(isoPath, opts...)
// after
if downloader.IsLocal(isoPath) {
    // handle local file directly, skip cache lookup
} else {
    res, err = downloader.Cached(isoPath, opts...)
}

if downloader.IsLocal(remote) {
    // bypass the cache entirely for local paths / file:// URLs
    return handleLocalFile(remote)
}

res, err := downloader.Cached(remote, opts...)
if err != nil && strings.Contains(err.Error(), "local files are not cached") {
    return handleLocalFile(remote) // fallback path for file:// or bare paths
}

When it happens

Trigger: Calling downloader.Cached("/path/to/file.iso"), Cached("~/image.qcow2"), or Cached("file:///abs/path") — any remote string where IsLocal() returns true.

Common situations: Configuration switched a template's image URL to a local file during testing and the code still goes through the caching path; users passing file:// URLs copied from docs assuming uniform behavior.

Related errors

• failed to close raw tmp file %q: %w
• failed to remove stale raw image %q: %w
• failed to replace original with raw image: %w
• failed to calculate digest of raw image: %w
• failed to write raw digest file: %w

AI-assisted analysis of lima-vm/lima@dd909d0973 (2026-09-01). Data as JSON: /api/errors/fe1887c096be890c. Report an issue: GitHub.