slimtoolkit/slim · error

dockerimage.LoadPackage: layer path mismatch - %v / %v

Error message

dockerimage.LoadPackage: layer path mismatch - %v / %v

What it means

LoadPackage cross-checks each layer's declared filesystem path (layerLocationInfo.Path from the manifest) against the path recorded on the loaded layer object (layer.Path). A mismatch means the archive's location metadata and the loaded layer disagree — the resolved blob does not correspond to the manifest entry, so proceeding could attribute the wrong filesystem contents to the image.

Source

Thrown at pkg/docker/dockerimage/dockerimage.go:1165

		layerLocationSource, layerSequence, archivePath)

	for idx, layerLocationInfo := range layerSequence {
		layer, ok := layers[layerLocationInfo.LayerID]
		if !ok {
			log.Errorf("dockerimage.LoadPackage: error missing layer (idx=%d layerPath=%s layerID=%s) archive=%s",
				idx, layerLocationInfo.Path, layerLocationInfo.LayerID, archivePath)
			return nil, fmt.Errorf("dockerimage.LoadPackage: missing layer (%v) for image ID - %v", layerLocationInfo.Path, imageID)
		}

		layer.Index = idx
		//adding layers based on their manifest order
		pkg.Layers = append(pkg.Layers, layer)
		if len(pkg.Layers)-1 != layer.Index {
			return nil, fmt.Errorf("dockerimage.LoadPackage: layer index mismatch - %v / %v", len(pkg.Layers)-1, layer.Index)
		}

		if layerLocationInfo.Path != layer.Path {
			return nil, fmt.Errorf("dockerimage.LoadPackage: layer path mismatch - %v / %v", layerLocationInfo.Path, layer.Path)
		}

		if idx == 0 {
			for oidx, object := range layer.Objects {
				object.LayerIndex = idx

				if utf8Detector != nil {
					switch object.ContentType {
					case ContentTypeUTF8:
						layer.Stats.UTF8Count++
						layer.Stats.UTF8Size += uint64(object.Size)
						pkg.Stats.UTF8Count++
						pkg.Stats.UTF8Size += uint64(object.Size)
					case ContentTypeBinary:
						layer.Stats.BinaryCount++
						layer.Stats.BinarySize += uint64(object.Size)
						pkg.Stats.BinaryCount++
						pkg.Stats.BinarySize += uint64(object.Size)

View on GitHub (pinned to 81940d17fa)

Solutions

  1. Re-export the archive so manifest layer paths match the stored blob locations one-to-one.
  2. Check whether any pre-processing moved/renamed blobs and undo or update the manifest location entries to match.
  3. Clear any layer cache that could return stale layer objects with outdated Path values, then retry the load.
  4. Compare the two paths in the error message to identify which side is stale and correct that artifact.

Example fix

// before: blob renamed after manifest written
$ mv blobs/sha256/abc... blobs/sha256/xyz...
// after: keep digests as-is
$ crane pull app:1.0 app.tar   # manifest paths match blob digests
Defensive patterns

Strategy: validation

Validate before calling

// ensure every manifest layer path exists at its expected location before load
func layerPathsExist(locs []struct{ Path string }) error {
	for _, l := range locs {
		if _, err := os.Stat(l.Path); err != nil {
			return fmt.Errorf("layer path %s missing: %w", l.Path, err)
		}
	}
	return nil
}

Type guard

func pathsMatch(locPath, layerPath string) bool { return filepath.Clean(locPath) == filepath.Clean(layerPath) }

Try / catch

pkg, err := dockerimage.LoadPackage(...)
if err != nil && strings.Contains(err.Error(), "layer path mismatch") {
	// fix blob locations or re-export; compare both paths in the error
}

Prevention

When it happens

Trigger: Calling LoadPackage where a manifest layer location resolves to a layer object loaded from a different path — e.g. blobs moved/renamed after indexing, symlinks pointing elsewhere, digest-keyed directories remapped, or a loader cache returning a layer keyed by ID but recorded with a different path.

Common situations: Post-processing tools that reorganize OCI blob directories; archives extracted with symlinks resolved differently; merging archives where the same layer digest exists at multiple paths and the wrong one is picked.

Related errors

AI-assisted analysis of slimtoolkit/slim@81940d17fa (2026-08-31). Data as JSON: /api/errors/b511eeea63094f03. Report an issue: GitHub.