What causes "image reference metadata get error - %s (%v)" in slimtoolkit/slim?

Verify the image exists: 'docker manifest inspect ' or curl the /v2/ /manifests/ endpoint

image reference metadata get error - %s (%v)

Error message

image reference metadata get error - %s (%v)

What it means

remote.Get(imgRef) failed to fetch metadata for a constituent image. Parse succeeded but the registry call failed — the image doesn't exist, the registry is unreachable, or auth failed. The original error is wrapped with the offending image name.

Source

Thrown at pkg/app/master/command/registry/handler_image_index.go:123

			logger.Debug("no image index in registry (ok)")
		} else {
			logger.Debugf("error checking image index in registry - %v", err)
		}
	} else {
		logger.Debug("image index is already in the registry")
	}

	imageIndex := v1.ImageIndex(empty.Index)
	indexImageImgRefs := make([]mutate.IndexAddendum, 0, len(cparams.ImageNames))
	for _, imageName := range cparams.ImageNames {
		imgRef, err := name.ParseReference(imageName, nameOpts...)
		if err != nil {
			xc.FailOn(fmt.Errorf("malformed image reference - %s (%v)", imageName, err))
		}

		meta, err := remote.Get(imgRef, remoteOpts...)
		if err != nil {
			xc.FailOn(fmt.Errorf("image reference metadata get error - %s (%v)", imageName, err))
		}

		if meta.MediaType.IsImage() {
			imgMeta, err := meta.Image()
			xc.FailOn(err)

			basicImageInfo(xc, imgMeta)

			imgConfig, err := imgMeta.ConfigFile()
			if err != nil {
				xc.FailOn(err)
			}
			imgRefMeta, err := partial.Descriptor(imgMeta)
			if err != nil {
				xc.FailOn(err)
			}
			imgRefMeta.Platform = imgConfig.Platform()
			indexImageImgRefs = append(indexImageImgRefs,

View on GitHub (pinned to 81940d17fa)

Solutions

Verify the image exists: 'docker manifest inspect <ref>' or curl the /v2/<repo>/manifests/<tag> endpoint
Push the constituent images before creating the index
Fix credentials (account/secret or UseDockerCreds) for private registries
Check network/DNS/TLS connectivity to the registry host

Example fix

// before
remote.Get(imgRef) // fails: app:v1-arm64 never pushed
// after
docker push registry.example.com/app:v1-arm64 # then retry index create

Defensive patterns

Strategy: validation

Validate before calling

for _, n := range ImageNames {
    ref, _ := name.ParseReference(n)
    if _, err := remote.Head(ref, remoteOpts...); err != nil {
        return fmt.Errorf("image %s not reachable: %w", n, err)
    }
}

Try / catch

if _, err := remote.Get(imgRef, remoteOpts...); err != nil {
    var terr *transport.Error
    if errors.As(err, &terr) && terr.StatusCode == 404 {
        // image missing: push it first
    } else if errors.As(err, &terr) && (terr.StatusCode == 401 || terr.StatusCode == 403) {
        // fix credentials
    }
    return err
}

Prevention

Push all constituent images before creating the index
Verify reachability with docker manifest inspect first
Keep credentials configured for private registries
Check registry DNS/TLS connectivity from the run environment

When it happens

Trigger: remote.Get returns an error for any entry in ImageNames: image tag not pushed yet, wrong registry host, expired/missing token (transport.Error 401/403), DNS failure, or TLS problems.

Common situations: Referencing arch-specific tags that were never pushed; typo in the tag; pushing to a private registry with bad creds; corporate proxy blocking the registry; offline environment.

Related errors

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