What causes "error during initial scan of %s" in kopia/kopia?

Clear the cache directory so the initial scan starts from an empty state (caches are disposable).

error during initial scan of

Error message

error during initial scan of %s

What it means

After the storage health check passes, NewPersistentCache runs initialScan to index existing cache entries; failure is wrapped as "error during initial scan of <description>". The persistent cache could not be constructed because its existing contents could not be inventoried.

Solutions

Clear the cache directory so the initial scan starts from an empty state (caches are disposable).
Fix underlying filesystem/permission problems indicated by the wrapped error.
Run filesystem repair tools if the wrapped error suggests I/O or corruption.
Upgrade kopia if the cache format changed between versions and the dir predates it.

Example fix

// before
error during initial scan of persistent-cache: error listing ...
// after
$ rm -rf ~/.cache/kopia/blob-cache ~/.cache/kopia/contents
$ kopia repository connect ...

Defensive patterns

Strategy: fallback

Validate before calling

// clean start if the cache dir looks suspect
if fi, err := os.Stat(cacheDir); err == nil && fi.IsDir() {
    if _, lerr := os.ReadDir(cacheDir); lerr != nil {
        os.RemoveAll(cacheDir)
    }
}

Try / catch

pc, err := cache.NewPersistentCache(ctx, ...)
if err != nil {
    if strings.Contains(err.Error(), "error during initial scan") {
        log.Warnf("clearing corrupt cache: %v", err)
        _ = os.RemoveAll(cacheDir)
        pc, err = cache.NewPersistentCache(ctx, ...)
    }
}

Prevention

Automatically wipe and rebuild the cache when initial scans fail — caches are disposable.
After crashes or power loss, proactively clear caches on next startup.
Do not reuse cache directories across repository format versions.
Run periodic filesystem checks on volumes holding caches.

When it happens

Trigger: NewPersistentCache where initialScan returns an error — practically any per-item failure surfaced by the list operation (see error 832's storage walk errors) such as corrupt entries, permission errors on shard dirs, or I/O failures.

Common situations: Crash-interrupted cache writes leaving unreadable entries; cache dir shared between different kopia versions/users with mismatched permissions; failing disk sectors in the cache volume.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

AI-assisted analysis of kopia/kopia@82495e54b5 (2026-09-07). Data as JSON: /api/errors/65f56a85e0a8d781. Report an issue: GitHub.

Appendix: source

Thrown at internal/cache/persistent_lru_cache.go:466

		metricsStruct:     initMetricsStruct(mr, description),
		listCache:         newContentMetadataHeap(),
		timeNow:           timeNow,
		lastCacheWarning:  time.Time{},
	}

	if c.timeNow == nil {
		c.timeNow = clock.Now
	}

	// verify that cache storage is functional by listing from it
	if _, err := c.cacheStorage.GetMetadata(ctx, "test-blob"); err != nil && !errors.Is(err, blob.ErrBlobNotFound) {
		return nil, errors.Wrapf(err, "unable to open %v", c.description)
	}

	releasable.Created("persistent-cache", c)

	if err := c.initialScan(ctx); err != nil {
		return nil, errors.Wrapf(err, "error during initial scan of %s", c.description)
	}

	return c, nil
}

View on GitHub (pinned to 82495e54b5)