wagoodman/dive · warning

path error at layer index %s: %s

Error message

path error at layer index %s: %s

What it means

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.

Source

Thrown at dive/filetree/comparer.go:153

			}

			indexes <- TreeIndexKey{
				bottomTreeStart: bottomTreeStart,
				bottomTreeStop:  bottomTreeStop,
				topTreeStart:    topTreeStart,
				topTreeStop:     topTreeStop,
			}
		}
	}()
	return indexes
}

func (cmp *Comparer) BuildCache() (errors []error) {
	for index := range cmp.NaturalIndexes() {
		pathError, _ := cmp.GetPathErrors(index)
		if len(pathError) > 0 {
			for _, path := range pathError {
				errors = append(errors, fmt.Errorf("path error at layer index %s: %s", index, path))
			}
		}
		_, err := cmp.GetTree(index)
		if err != nil {
			errors = append(errors, err)
			return errors
		}
	}

	for index := range cmp.AggregatedIndexes() {
		_, err := cmp.GetTree(index)
		if err != nil {
			errors = append(errors, err)
			return errors
		}
	}
	return errors
}

View on GitHub (pinned to d6c691947f)

Solutions

1. Treat as non-fatal: dive still runs; note the reported paths to see which files' diff info may be inaccurate
2. Re-pull the image from the source registry to rule out corrupted layer downloads
3. If you control the image build, avoid whiteouts of non-existent paths (check with: docker export and inspect .wh. entries)
4. Report upstream with the image reference if a stock image (e.g. official library image) triggers it

// pre-check whiteout targets exist in the lower stack (custom analysis pipelines)
// skip images whose layers contain whiteouts for absent paths when strict diff accuracy is required

errs := cmp.BuildCache()
for _, err := range errs {
    if strings.Contains(err.Error(), "path error at layer index") {
        // non-fatal: record and continue; these are per-path warnings
        log.WithFields("error", err).Warn("path inconsistency in image layers")
    } else {
        return err // real build failure
    }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• unable to fetch layer tree from cache: %w
• failed to build tree: %w
• file tree has path errors (use '--ignore-errors' to attempt
• could not add child node: '%s' (path:'%s')
• notifyOnViewOptionChangeListeners error: %w

AI-assisted analysis of wagoodman/dive@d6c691947f (2026-08-15). Data as JSON: /api/errors/43d88d7f50ac657b. Report an issue: GitHub.