dockerimage.LoadPackage: missing layer (%v) for image ID - %

Error message

dockerimage.LoadPackage: missing layer (%v) for image ID - %v

What it means

After loading all layer blobs, LoadPackage walks the manifest's layer sequence and requires each referenced layer ID to exist in the loaded layers map. A missing entry means a layer blob named by the manifest (layerLocationInfo.LayerID) was not found in the archive; the error reports the expected layer path and image ID.

Source

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

		//todo: save non-image layer metadata/data
		log.Debugf("dockerimage.LoadPackage: no image layers in archive - %s (%+v)",
			archivePath, layerFileNames)
	}

	if len(nonLayerFileNames) > 0 {
		log.Debugf("dockerimage.LoadPackage: non-image layers in archive - %s (%s)",
			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 {

View on GitHub (pinned to 81940d17fa)

Solutions

Re-create the archive so every manifest layer blob is present (full `docker save` / `crane pull`).
Check the logged layerPath/layerID against the archive contents and restore the missing blob at the expected path.
Run a completeness check (skopeo copy with --all, or tar -tf and compare layer digests to the manifest) before ingestion.
If the layer is legitimately absent, rebuild the image so all layers are regenerated.

Example fix

// before: partial archive
$ docker save myimage:1.0 | gzip > partial.tar.gz   # interrupted
// after: complete export
$ docker save -o full.tar myimage:1.0 && tar -tf full.tar | wc -l   # verify all layers

Defensive patterns

Strategy: validation

Validate before calling

// compare manifest layer digests to archive contents before LoadPackage
func allLayersPresent(files []string, layerDigests []string) error {
	for _, d := range layerDigests {
		found := false
		for _, f := range files {
			if strings.Contains(f, d) { found = true; break }
		}
		if !found { return fmt.Errorf("layer %s missing from archive", d) }
	}
	return nil
}

Type guard

func layerCount(p *dockerimage.Package, want int) bool { return p != nil && len(p.Layers) == want }

Try / catch

pkg, err := dockerimage.LoadPackage(...)
if err != nil && strings.Contains(err.Error(), "missing layer") {
	// re-download/re-save the image; verify layer digests first next time
}

Prevention

Use complete exports (docker save / crane pull) and avoid interrupted copies
Compare tar contents to manifest digests before ingestion
Avoid registry GC or blob pruning on images still being exported

When it happens

Trigger: Calling LoadPackage where the manifest references a layer that is absent from the archive files: truncated download, layers pruned from a saved image, duplicate/deduplicated layer files removed, or layer digest mismatch between manifest and stored blob.

Common situations: Images shipped with shared/removed layers after aggressive registry GC; partial `docker save` of only some tags' layers; interrupted skopeo/crane copies; corporate proxies caching manifests but not all blobs.

Related errors

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