What causes "saving image index error - %s (%v)" in slimtoolkit/slim?

Retry the push after checking network stability — blob uploads are resumable

saving image index error - %s (%v)

Error message

saving image index error - %s (%v)

What it means

The handler failed to write the assembled image index to the registry (remote.Write). When the error is not a recoverable exit-path case, it is wrapped as 'saving image index error' with the target index name and underlying error.

Source

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

	imageIndex = mutate.AppendManifests(imageIndex, indexImageImgRefs...)

	if err := remote.WriteIndex(imageIndexRef, imageIndex, remoteOpts...); err != nil {
		var terr *transport.Error
		if errors.As(err, &terr) && terr.StatusCode == http.StatusUnauthorized {
			xc.Out.Info("registry.auth.error",
				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)

View on GitHub (pinned to 81940d17fa)

Solutions

Retry the push after checking network stability — blob uploads are resumable
Fix credentials/scopes so the account has push permission to the repository
Check registry quota and immutability/retention policies
Ensure the target repository exists or can be auto-created by your account

Example fix

// before
remote.Write(imageIndexRef, imageIndex, remoteOpts...)
// after
remote.Write(imageIndexRef, imageIndex, append(remoteOpts,
  remote.WithAuth(auth.FromConfig(cparams.CredsAccount, cparams.CredsSecret)))...)

Defensive patterns

Strategy: retry

Validate before calling

// pre-check push permissions
if err := checkPushAccess(registry, creds); err != nil {
    return err
}

Try / catch

err := remote.Write(imageIndexRef, imageIndex, remoteOpts...)
if err != nil {
    var terr *transport.Error
    if errors.As(err, &terr) && (terr.StatusCode == 429 || terr.StatusCode >= 500 || isTransient(err)) {
        time.Sleep(backoff)
        err = remote.Write(imageIndexRef, imageIndex, remoteOpts...)
    }
    return err
}

Prevention

Confirm the account has push rights and the repo isn't read-only
Watch registry quota/rate limits (especially Docker Hub)
Use stable network paths for large multi-arch pushes; avoid aggressive proxies
Retry transient failures with exponential backoff

When it happens

Trigger: remote.Write(imageIndexRef) fails during push: auth rejected (401/403), registry read-only or quota exceeded, network interruption mid-upload, blob upload rejected, or the target tag is immutable.

Common situations: Pushing to Docker Hub on a free plan out of pulls/storage; immutable tags enabled on the registry; proxy/firewall cutting long uploads; token expiring during large multi-arch pushes.

Related errors

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