docker/cli · error · notFoundError

no such manifest: {ref}

Error message

no such manifest: {ref}

What it means

Returned by iterateEndpoints (internal/registryclient/fetcher.go:274) as a notFoundError after exhausting all registry endpoints without successfully fetching the requested manifest. notFoundError implements NotFound() so callers can detect it via errors.As or type assertion. The named reference string is appended so the caller knows which image/tag was not found.

Source

Thrown at internal/registryclient/fetcher.go:274

			continue
		}
		done, err := each(ctx, repo, namedRef)
		if err != nil {
			if continueOnError(err) {
				if endpoint.URL.Scheme == "https" {
					confirmedTLSRegistries[endpoint.URL.Host] = true
				}
				logrus.Debugf("continuing on error (%T) %s", err, err)
				continue
			}
			logrus.Debugf("not continuing on error (%T) %s", err, err)
			return err
		}
		if done {
			return nil
		}
	}
	return notFoundError{errors.New("no such manifest: " + namedRef.String())}
}

// allEndpoints returns a list of endpoints ordered by priority (v2, http).
func allEndpoints(ctx context.Context, namedRef reference.Named, insecure bool) ([]registry.APIEndpoint, error) {
	var serviceOpts registry.ServiceOptions
	if insecure {
		logrus.Debugf("allowing insecure registry for: %s", reference.Domain(namedRef))
		serviceOpts.InsecureRegistries = []string{reference.Domain(namedRef)}
	}
	registryService, err := registry.NewService(serviceOpts)
	if err != nil {
		return nil, err
	}
	endpoints, err := registryService.Endpoints(ctx, reference.Domain(namedRef))
	logrus.Debugf("endpoints for %s: %v", namedRef, endpoints)
	return endpoints, err
}

View on GitHub (pinned to 4f84911bfe)

Solutions

1. Verify the image reference is correct: check spelling of registry, repository, and tag with 'docker manifest inspect <image>'.
2. Ensure you are authenticated to the registry: run 'docker login <registry>' if using a private registry.
3. Check if the tag actually exists by browsing the registry UI or API.
4. If using a registry mirror, verify the mirror has the image or configure fallback to the upstream registry.

Example fix

// before: generic error handling
img, err := fetcher.GetManifest(ctx, ref)
if err != nil {
    return err // 'no such manifest: myregistry.com/foo:bar'
}

// after: detect not-found specifically
img, err := fetcher.GetManifest(ctx, ref)
if err != nil {
    var nf notFoundError
    if errors.As(err, &nf) {
        return fmt.Errorf("image %s not found on any configured registry endpoint", ref)
    }
    return err
}

// Check image existence before deep operations
func imageExists(ctx context.Context, cli *client.Client, ref string) bool {
    _, _, err := cli.ImageInspectWithRaw(ctx, ref)
    return err == nil || !client.IsErrNotFound(err)
}

// notFoundError implements NotFound() — use errors.As to detect
func isManifestNotFound(err error) bool {
    var nf notFoundError
    return errors.As(err, &nf)
}

manifest, err := fetcher.GetManifest(ctx, namedRef)
if err != nil {
    var nf notFoundError
    if errors.As(err, &nf) {
        return fmt.Errorf("image %s does not exist on any registry endpoint", namedRef)
    }
    return err
}

When it happens

Trigger: fetchManifest or fetchList calls iterateEndpoints, which loops over all discovered endpoints (registry mirrors, v2/v1). For each endpoint, the manifest fetch returns a 'continuable' error (404 manifest unknown, 401 unauthorized, name unknown, or unexpected HTTP response), so iteration continues. After all endpoints are exhausted with no success, notFoundError wraps 'no such manifest: <ref>'.

Common situations: Image or tag does not exist on the registry, typo in image name or tag, using a private registry without being logged in (all endpoints return 401 → continue → exhausted), registry mirror misconfiguration, or the image exists on a different registry than configured.

Related errors

• refusing to amend an existing manifest list with no --amend
• manifest for image %s does not exist in %s
• failed to assemble ManifestDescriptor: %w
• %s not found
• manifest %s must have an OS and Architecture to be pushed to

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/0db5293c7c252135. Report an issue: GitHub.