dockerimage.LoadPackage: missing manifest object for image I

Error message

dockerimage.LoadPackage: missing manifest object for image ID=%s / archive='%s' / files=%+v

What it means

dockerimage.LoadPackage validates that, for non-OCI (docker save style) packages, the Docker manifest object was loaded. A nil pkg.Manifest means the archive did not contain a usable manifest.json for the imageID, so loading aborts with the image ID, archive path, and file list to aid diagnosis.

Source

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

						log.Errorf("dockerimage.LoadPackage: error reading oci layer from archive(%s/%s) - %v", archivePath, hdr.Name, err)
						return nil, err
					}
					layers[layerID] = layer
					log.Debugf("dockerimage.LoadPackage: saved layer '%s' from archive - %s",
						layerID, archivePath)
				}
			}
		}
	}

	if pkg.Format == FormatOCI {
		if pkg.ManifestOCI == nil {
			return nil, fmt.Errorf("dockerimage.LoadPackage: missing OCI Image Manifest object for image ID=%s / archive='%s' / files=%+v",
				imageID, archivePath, archiveFiles)
		}
	} else {
		if pkg.Manifest == nil {
			return nil, fmt.Errorf("dockerimage.LoadPackage: missing manifest object for image ID=%s / archive='%s' / files=%+v",
				imageID, archivePath, archiveFiles)
		}
	}

	if pkg.Config == nil {
		return nil, fmt.Errorf("dockerimage.LoadPackage: missing image config object for image ID=%s / archive='%s' / files=%+v",
			imageID, archivePath, archiveFiles)
	}

	if len(layers) == 0 {
		//todo: display non-image layer metadata if there are any
		//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)",

View on GitHub (pinned to 81940d17fa)

Solutions

Re-run `docker save -o image.tar image:tag` on the source image to regenerate a complete archive with manifest.json.
Verify the archive contains manifest.json (`tar -tf image.tar | grep manifest.json`) and that its RepoTags/Digests reference the target imageID.
Check whether the archive is actually OCI layout and ensure the loader detects FormatOCI so the OCI manifest path is used instead.

Example fix

// before: tar built without manifest.json
$ tar -cf image.tar layers/ config.json
// after
$ docker save -o image.tar myimage:1.0

Defensive patterns

Strategy: validation

Validate before calling

func hasManifestJSON(archivePath string) error {
	f, err := os.Open(archivePath)
	if err != nil { return err }
	defer f.Close()
	tr := tar.NewReader(f)
	for {
		h, err := tr.Next()
		if err == io.EOF { return errors.New("manifest.json not found in archive") }
		if err != nil { return err }
		if h.Name == "manifest.json" { return nil }
	}
}

Type guard

func isDockerArchive(p *dockerimage.Package) bool { return p != nil && p.Format != dockerimage.FormatOCI }

Try / catch

pkg, err := dockerimage.LoadPackage(...)
if err != nil && strings.Contains(err.Error(), "missing manifest object") {
	// regenerate archive with docker save or detect OCI format instead
}

Prevention

Always create docker archives with `docker save -o`, never by hand-assembling tars
Check tar completion when piping downloads (set -o pipefail)
Confirm format detection matches the archive type before loading

When it happens

Trigger: Calling LoadPackage on a docker-save format archive whose manifest.json is missing, unreadable, empty, or does not reference the requested imageID — e.g. legacy format archives, truncated tarballs, or OCI archives misclassified as docker format.

Common situations: Older `docker save` outputs or hand-assembled tars lacking manifest.json; archives created by piping (curl | tar) that were cut short; mixing OCI blobs into a package detected as FormatDocker.

Related errors

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