slimtoolkit/slim · error

malformed image reference - %s (%v)

Error message

malformed image reference - %s (%v)

What it means

One of the constituent image references in cparams.ImageNames failed name.ParseReference validation. Same reference-syntax rules as the index name, applied per member image; the handler reports which imageName was malformed.

Source

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

		xc.FailOn(fmt.Errorf("malformed image index reference - %s (%v)", cparams.ImageIndexName, err))
	}

	if _, err := remote.Head(imageIndexRef, remoteOpts...); err != nil {
		if _, ok := err.(*transport.Error); ok {
			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)

View on GitHub (pinned to 81940d17fa)

Solutions

1. Validate each image reference string (lowercase repo, valid tag charset [A-Za-z0-9_][A-Za-z0-9._-]{0,127})
2. Trim whitespace and split comma lists carefully
3. Do not combine tag and digest in one reference
4. Normalize short names to fully qualified ones (docker.io/library/nginx:latest)

Example fix

// before
ImageNames: []string{" registry.example.com/App:v1-amd64 "}
// after
ImageNames: []string{"registry.example.com/app:v1-amd64"}

import "github.com/google/go-containerregistry/pkg/name"
for _, n := range ImageNames {
    if _, err := name.ParseReference(strings.TrimSpace(n)); err != nil {
        return fmt.Errorf("invalid ref %q: %w", n, err)
    }
}

func isValidRef(s string) bool {
    _, err := name.ParseReference(strings.TrimSpace(s))
    return err == nil
}

When it happens

Trigger: Iterating ImageNames where any entry violates reference syntax — uppercase repo, invalid tag/digest combination, empty string, or stray characters introduced by shell expansion.

Common situations: Building multi-arch indexes where per-arch tags are generated with templates producing bad names; copy-pasted references with 'docker.io/' mixed with short names inconsistently; whitespace in comma-separated lists.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• malformed Kubernetes workload name
• podPort cannot be empty
• cannot detect host port
• file path is not absolute
• file is not a binary

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