slimtoolkit/slim · error

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

Error message

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

What it means

While appending layers in manifest order, LoadPackage asserts the slice position (len(pkg.Layers)-1) equals the layer's stored Index. A mismatch means internal bookkeeping is inconsistent — the layer was loaded/indexed out of order or the index was mutated, so the package would misrepresent layer ordering (which is semantically critical for images).

Source

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

			archivePath, jsonutil.ToString(nonLayerFileNames))
	}

	log.Debugf("dockerimage.LoadPackage: layerLocationSource=%v layerSequence='%#v' - archive='%s'",
		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:

View on GitHub (pinned to 81940d17fa)

Solutions

  1. Regenerate the archive from the source image so manifest order and layer metadata are consistent.
  2. Check for duplicate layer entries in the manifest (diff_ids appearing twice) and rebuild the image if found.
  3. If caused by custom pre-processing code that mutates layer indexes, remove the mutation and let LoadPackage assign indexes.

Example fix

// before: reordered manifest layers
"layers": ["sha256:b...", "sha256:a..."]  // wrong order
// after: rebuild/export preserving order
$ docker save -o image.tar myimage:1.0
Defensive patterns

Strategy: validation

Validate before calling

// detect duplicate or reordered layer entries before load
func layerIDsUnique(manifestLayerIDs []string) bool {
	seen := map[string]bool{}
	for _, id := range manifestLayerIDs {
		if seen[id] { return false }
		seen[id] = true
	}
	return true
}

Try / catch

pkg, err := dockerimage.LoadPackage(...)
if err != nil && strings.Contains(err.Error(), "layer index mismatch") {
	// treat archive as corrupt; regenerate it — do not retry in place
}

Prevention

When it happens

Trigger: LoadPackage encountering a layer whose recorded Index does not match its position in the manifest's layer sequence — typically from corrupted/edited manifest ordering, duplicated layers, or a loader bug populating layer.Index inconsistently.

Common situations: Hand-edited or tool-rewritten manifests where layer entries were reordered or duplicated; archives assembled from mixed sources; cache layers reused with stale index metadata.

Related errors

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