slimtoolkit/slim · error

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

Error message

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

What it means

After saving, the handler re-reads the index with remote.Index(imageIndexRef) to verify it; this fetch failed. The wrapped error names the index reference and the underlying cause.

Source

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

				ovars{
					"message": "need to authenticate",
				})

			exitCode := -111
			xc.Out.State("exited",
				ovars{
					"exit.code": exitCode,
					"version":   v.Current(),
				})
			xc.Exit(exitCode)
		} else {
			xc.FailOn(fmt.Errorf("saving image index error - %s (%v)", cparams.ImageIndexName, err))
		}
	}

	indexMeta, err := remote.Index(imageIndexRef, remoteOpts...)
	if err != nil {
		xc.FailOn(fmt.Errorf("index reference metadata get error - %s (%v)", cparams.ImageIndexName, err))
	}

	indexMediaType, err := indexMeta.MediaType()
	xc.FailOn(err)

	if !indexMediaType.IsIndex() {
		xc.FailOn(fmt.Errorf("unexpected media type for index"))
	}

	indexDigest, err := indexMeta.Digest()
	xc.FailOn(err)

	indexManifest, err := indexMeta.IndexManifest()
	xc.FailOn(err)
	xc.Out.Info("index.info",
		ovars{
			"reference":                imageIndexRef,
			"digest":                   indexDigest.String(),

View on GitHub (pinned to 81940d17fa)

Solutions

1. Retry the verification fetch after a short delay
2. Use the same auth options for read as were used for the write
3. Verify the manifest actually landed: 'docker manifest inspect <index-ref>'
4. If the registry is a cache/mirror, query the upstream registry directly

Example fix

// before
indexMeta, err := remote.Index(imageIndexRef, remoteOpts...)
// after
indexMeta, err := remote.Index(imageIndexRef, append(remoteOpts,
  remote.WithAuthFromKeychain(authn.DefaultKeychain))...)

// verify with a small retry loop after push
var indexMeta *remote.Descriptor
for i := 0; i < 3; i++ {
    if indexMeta, err = remote.Index(imageIndexRef, remoteOpts...); err == nil {
        break
    }
    time.Sleep(2 * time.Second)
}

indexMeta, err := remote.Index(imageIndexRef, remoteOpts...)
if err != nil {
    if isTransient(err) {
        // retry with backoff before failing
    }
    return fmt.Errorf("index verify failed for %s: %w", imageIndexRef.Name(), err)
}

When it happens

Trigger: remote.Index fails right after a (possibly reported-as-failed or skipped) save: eventual-consistency lag on the registry, auth mismatch between write and read, or network errors.

Common situations: Mirroring/proxy registries (e.g. pull-through caches) that don't immediately serve freshly pushed manifests; reading anonymously right after an authenticated push; transient network blips.

Related errors

• image reference metadata get error - %s (%v)
• saving image index error - %s (%v)
• slim: error => no network info
• slim: error => missing comms ports
• could not find an auth config for registry - %s

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