{"record":{"id":"65f56a85e0a8d781","repo":"kopia/kopia","slug":"error-during-initial-scan-of-s","errorCode":null,"errorMessage":"error during initial scan of %s","messagePattern":"error during initial scan of (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/cache/persistent_lru_cache.go","lineNumber":466,"sourceCode":"\t\tmetricsStruct:     initMetricsStruct(mr, description),\n\t\tlistCache:         newContentMetadataHeap(),\n\t\ttimeNow:           timeNow,\n\t\tlastCacheWarning:  time.Time{},\n\t}\n\n\tif c.timeNow == nil {\n\t\tc.timeNow = clock.Now\n\t}\n\n\t// verify that cache storage is functional by listing from it\n\tif _, err := c.cacheStorage.GetMetadata(ctx, \"test-blob\"); err != nil && !errors.Is(err, blob.ErrBlobNotFound) {\n\t\treturn nil, errors.Wrapf(err, \"unable to open %v\", c.description)\n\t}\n\n\treleasable.Created(\"persistent-cache\", c)\n\n\tif err := c.initialScan(ctx); err != nil {\n\t\treturn nil, errors.Wrapf(err, \"error during initial scan of %s\", c.description)\n\t}\n\n\treturn c, nil\n}\n","sourceCodeStart":448,"sourceCodeEnd":471,"githubUrl":"https://github.com/kopia/kopia/blob/82495e54b584c1ef6073c9e1be048f57f8aef078/internal/cache/persistent_lru_cache.go#L448-L471","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nerror during initial scan of persistent-cache: error listing ...\n// after\n$ rm -rf ~/.cache/kopia/blob-cache ~/.cache/kopia/contents\n$ kopia repository connect ...","handlingStrategy":"fallback","validationCode":"// clean start if the cache dir looks suspect\nif fi, err := os.Stat(cacheDir); err == nil && fi.IsDir() {\n    if _, lerr := os.ReadDir(cacheDir); lerr != nil {\n        os.RemoveAll(cacheDir)\n    }\n}","typeGuard":null,"tryCatchPattern":"pc, err := cache.NewPersistentCache(ctx, ...)\nif err != nil {\n    if strings.Contains(err.Error(), \"error during initial scan\") {\n        log.Warnf(\"clearing corrupt cache: %v\", err)\n        _ = os.RemoveAll(cacheDir)\n        pc, err = cache.NewPersistentCache(ctx, ...)\n    }\n}","preventionTips":["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."],"tags":["cache","initial-scan","lru-cache","kopia"],"backgroundTag":"file-read-failed","analyzedSha":"82495e54b584c1ef6073c9e1be048f57f8aef078","analyzedAt":"2026-09-07T20:35:21.689Z","contentChangedAt":"2026-09-07T20:35:21.689Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}