{"record":{"id":"43d88d7f50ac657b","repo":"wagoodman/dive","slug":"path-error-at-layer-index-s-s","errorCode":null,"errorMessage":"path error at layer index %s: %s","messagePattern":"path error at layer index (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"dive/filetree/comparer.go","lineNumber":153,"sourceCode":"\t\t\t}\n\n\t\t\tindexes <- TreeIndexKey{\n\t\t\t\tbottomTreeStart: bottomTreeStart,\n\t\t\t\tbottomTreeStop:  bottomTreeStop,\n\t\t\t\ttopTreeStart:    topTreeStart,\n\t\t\t\ttopTreeStop:     topTreeStop,\n\t\t\t}\n\t\t}\n\t}()\n\treturn indexes\n}\n\nfunc (cmp *Comparer) BuildCache() (errors []error) {\n\tfor index := range cmp.NaturalIndexes() {\n\t\tpathError, _ := cmp.GetPathErrors(index)\n\t\tif len(pathError) > 0 {\n\t\t\tfor _, path := range pathError {\n\t\t\t\terrors = append(errors, fmt.Errorf(\"path error at layer index %s: %s\", index, path))\n\t\t\t}\n\t\t}\n\t\t_, err := cmp.GetTree(index)\n\t\tif err != nil {\n\t\t\terrors = append(errors, err)\n\t\t\treturn errors\n\t\t}\n\t}\n\n\tfor index := range cmp.AggregatedIndexes() {\n\t\t_, err := cmp.GetTree(index)\n\t\tif err != nil {\n\t\t\terrors = append(errors, err)\n\t\t\treturn errors\n\t\t}\n\t}\n\treturn errors\n}","sourceCodeStart":135,"sourceCodeEnd":171,"githubUrl":"https://github.com/wagoodman/dive/blob/d6c691947f8fda635c952a17ee3b7555379d58f0/dive/filetree/comparer.go#L135-L171","documentation":"During BuildCache (pre-warming all natural per-layer and aggregated tree combinations), the comparer records PathError entries — individual paths that could not be added, removed (whiteout), or marked while stacking layers. Each becomes 'path error at layer index <key>: <path error>'. These are collected warnings about per-path inconsistencies in the image layers, not fatal build failures; GetTree errors abort separately.","triggerScenarios":"During BuildCache's iteration over NaturalIndexes, GetPathErrors(index) returning entries: AddPath failing on a graft, markRemoved failing for a whiteout (.wh.) path that doesn't exist in the lower stack, or similar per-path failures captured as PathError instead of aborting.","commonSituations":"OCI images with whiteout files that reference paths missing from lower layers (common with some buildkit/squashed images); layers with duplicate path entries of conflicting types (file vs dir); images from niche base images or hand-crafted tarballs; registry proxies that mangle layer tars.","solutions":["Treat as non-fatal: dive still runs; note the reported paths to see which files' diff info may be inaccurate","Re-pull the image from the source registry to rule out corrupted layer downloads","If you control the image build, avoid whiteouts of non-existent paths (check with: docker export and inspect .wh. entries)","Report upstream with the image reference if a stock image (e.g. official library image) triggers it"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"// pre-check whiteout targets exist in the lower stack (custom analysis pipelines)\n// skip images whose layers contain whiteouts for absent paths when strict diff accuracy is required","typeGuard":null,"tryCatchPattern":"errs := cmp.BuildCache()\nfor _, err := range errs {\n    if strings.Contains(err.Error(), \"path error at layer index\") {\n        // non-fatal: record and continue; these are per-path warnings\n        log.WithFields(\"error\", err).Warn(\"path inconsistency in image layers\")\n    } else {\n        return err // real build failure\n    }\n}","preventionTips":["Treat path errors as data-quality warnings, not aborts","Re-pull images when whiteout warnings appear after a flaky network pull","When building images, avoid whiteouts of non-existent paths (audit .wh. entries with docker export)"],"tags":["filetree","comparer","whiteout","image-data","warnings"],"backgroundTag":null,"analyzedSha":"d6c691947f8fda635c952a17ee3b7555379d58f0","analyzedAt":"2026-08-15T09:42:35.293Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}