{"record":{"id":"d6930573c21bbd1b","repo":"slimtoolkit/slim","slug":"dockerimage-loadpackage-layer-index-mismatch-v","errorCode":null,"errorMessage":"dockerimage.LoadPackage: layer index mismatch - %v / %v","messagePattern":"dockerimage\\.LoadPackage: layer index mismatch - (.+?) / (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/docker/dockerimage/dockerimage.go","lineNumber":1161,"sourceCode":"\t\t\tarchivePath, jsonutil.ToString(nonLayerFileNames))\n\t}\n\n\tlog.Debugf(\"dockerimage.LoadPackage: layerLocationSource=%v layerSequence='%#v' - archive='%s'\",\n\t\tlayerLocationSource, layerSequence, archivePath)\n\n\tfor idx, layerLocationInfo := range layerSequence {\n\t\tlayer, ok := layers[layerLocationInfo.LayerID]\n\t\tif !ok {\n\t\t\tlog.Errorf(\"dockerimage.LoadPackage: error missing layer (idx=%d layerPath=%s layerID=%s) archive=%s\",\n\t\t\t\tidx, layerLocationInfo.Path, layerLocationInfo.LayerID, archivePath)\n\t\t\treturn nil, fmt.Errorf(\"dockerimage.LoadPackage: missing layer (%v) for image ID - %v\", layerLocationInfo.Path, imageID)\n\t\t}\n\n\t\tlayer.Index = idx\n\t\t//adding layers based on their manifest order\n\t\tpkg.Layers = append(pkg.Layers, layer)\n\t\tif len(pkg.Layers)-1 != layer.Index {\n\t\t\treturn nil, fmt.Errorf(\"dockerimage.LoadPackage: layer index mismatch - %v / %v\", len(pkg.Layers)-1, layer.Index)\n\t\t}\n\n\t\tif layerLocationInfo.Path != layer.Path {\n\t\t\treturn nil, fmt.Errorf(\"dockerimage.LoadPackage: layer path mismatch - %v / %v\", layerLocationInfo.Path, layer.Path)\n\t\t}\n\n\t\tif idx == 0 {\n\t\t\tfor oidx, object := range layer.Objects {\n\t\t\t\tobject.LayerIndex = idx\n\n\t\t\t\tif utf8Detector != nil {\n\t\t\t\t\tswitch object.ContentType {\n\t\t\t\t\tcase ContentTypeUTF8:\n\t\t\t\t\t\tlayer.Stats.UTF8Count++\n\t\t\t\t\t\tlayer.Stats.UTF8Size += uint64(object.Size)\n\t\t\t\t\t\tpkg.Stats.UTF8Count++\n\t\t\t\t\t\tpkg.Stats.UTF8Size += uint64(object.Size)\n\t\t\t\t\tcase ContentTypeBinary:","sourceCodeStart":1143,"sourceCodeEnd":1179,"githubUrl":"https://github.com/slimtoolkit/slim/blob/81940d17fa112cc678e32209214bcb2355cb3004/pkg/docker/dockerimage/dockerimage.go#L1143-L1179","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Regenerate the archive from the source image so manifest order and layer metadata are consistent.","Check for duplicate layer entries in the manifest (diff_ids appearing twice) and rebuild the image if found.","If caused by custom pre-processing code that mutates layer indexes, remove the mutation and let LoadPackage assign indexes."],"exampleFix":"// before: reordered manifest layers\n\"layers\": [\"sha256:b...\", \"sha256:a...\"]  // wrong order\n// after: rebuild/export preserving order\n$ docker save -o image.tar myimage:1.0","handlingStrategy":"validation","validationCode":"// detect duplicate or reordered layer entries before load\nfunc layerIDsUnique(manifestLayerIDs []string) bool {\n\tseen := map[string]bool{}\n\tfor _, id := range manifestLayerIDs {\n\t\tif seen[id] { return false }\n\t\tseen[id] = true\n\t}\n\treturn true\n}","typeGuard":null,"tryCatchPattern":"pkg, err := dockerimage.LoadPackage(...)\nif err != nil && strings.Contains(err.Error(), \"layer index mismatch\") {\n\t// treat archive as corrupt; regenerate it — do not retry in place\n}","preventionTips":["Do not reorder or deduplicate manifest layer entries with custom tooling","Let LoadPackage assign layer indexes; never mutate layer.Index upstream","Rebuild images whose manifests were edited by post-processing scripts"],"tags":["oci","layers","indexing","docker"],"backgroundTag":"layer-index-mismatch","analyzedSha":"81940d17fa112cc678e32209214bcb2355cb3004","analyzedAt":"2026-08-31T23:06:12.682Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}