containerd/containerd · error

InvalidArgument

InvalidArgument

Error message

ref source not supported: %w

What it means

Store in the transfer/image service builds image records from a descriptor's annotations. The annotation "io.containerd.import.ref-source" can mark the reference source as digest, tag, or prefix; the switch handles only known values, and any other value (or an unparseable one) falls into default and returns this InvalidArgument error. The client supplied a ref-source value the store does not understand.

Source

Thrown at core/transfer/image/imagestore.go:282

				imgs = append(imgs, images.Image{
					Name:   name,
					Target: desc,
					Labels: extraRefLabels(),
				})

				// If a named reference was found and SkipNamedDigest is true, do
				// not use this reference
				if ref.AddDigest && !ref.SkipNamedDigest {
					imgs = append(imgs, images.Image{
						Name:   fmt.Sprintf("%s@%s", ref.Name, desc.Digest),
						Target: desc,
						Labels: extraRefLabels(),
					})
				}
			}
		default:
			return nil, fmt.Errorf("ref source not supported: %w", errdefs.ErrInvalidArgument)
		}
		delete(desc.Annotations, "io.containerd.import.ref-source")
	} else {
		if is.imageName != "" {
			imgs = append(imgs, images.Image{
				Name:   is.imageName,
				Target: desc,
				Labels: is.imageLabels,
			})
		}

		// If extra references, store all complete references and prefix
		// references which add a digest (prefixes without a digest are skipped
		// since they have no concrete name to store).
		//
		// Note: SkipNamedDigest is intentionally not honored here. It applies
		// to the annotation branch where a named reference is resolved from a
		// descriptor's own annotations via the prefix — in that case a name

View on GitHub (pinned to 4246446a2b)

Solutions

1. Set the annotation to a supported value: "digest", "tag", or remove it entirely
2. Inspect the import request/manifest annotations for typos in io.containerd.import.ref-source
3. Align producer and consumer containerd versions so both understand the ref-source values in use

Example fix

// before
"io.containerd.import.ref-source": "tagName"
// after
"io.containerd.import.ref-source": "tag"

valid := map[string]bool{"digest": true, "tag": true}
if v, ok := desc.Annotations["io.containerd.import.ref-source"]; ok && !valid[v] {
    return fmt.Errorf("invalid ref-source annotation %q: must be digest or tag", v)
}

_, err := imageStore.Store(ctx, desc)
if err != nil {
    if errdefs.IsInvalidArgument(err) && strings.Contains(err.Error(), "ref source not supported") {
        // strip/fix the annotation and retry
        delete(desc.Annotations, "io.containerd.import.ref-source")
        _, err = imageStore.Store(ctx, desc)
    }
    return err
}

When it happens

Trigger: Store() processing an image descriptor whose desc.Annotations["io.containerd.import.ref-source"] is set to an unsupported value (anything other than digest/tag/prefix, or malformed) during image import via the transfer service.

Common situations: Hand-crafted or tool-generated import requests with a typo'd ref-source annotation; version mismatch where a newer producer sets a ref-source value the running containerd doesn't recognize.

Related errors

• NotFound
• Unimplemented
• container not created from an image: %w
• failed to get image %s for container: %w
• errdefs.ErrInvalidArgument

AI-assisted analysis of containerd/containerd@4246446a2b (2026-09-02). Data as JSON: /api/errors/7aa9a7fa36487ea6. Report an issue: GitHub.