{"record":{"id":"0db5293c7c252135","repo":"docker/cli","slug":"no-such-manifest-ref","errorCode":null,"errorMessage":"no such manifest: {ref}","messagePattern":"no such manifest: (.+?)","errorType":"exception","errorClass":"notFoundError","httpStatus":null,"severity":"error","filePath":"internal/registryclient/fetcher.go","lineNumber":274,"sourceCode":"\t\t\tcontinue\n\t\t}\n\t\tdone, err := each(ctx, repo, namedRef)\n\t\tif err != nil {\n\t\t\tif continueOnError(err) {\n\t\t\t\tif endpoint.URL.Scheme == \"https\" {\n\t\t\t\t\tconfirmedTLSRegistries[endpoint.URL.Host] = true\n\t\t\t\t}\n\t\t\t\tlogrus.Debugf(\"continuing on error (%T) %s\", err, err)\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\tlogrus.Debugf(\"not continuing on error (%T) %s\", err, err)\n\t\t\treturn err\n\t\t}\n\t\tif done {\n\t\t\treturn nil\n\t\t}\n\t}\n\treturn notFoundError{errors.New(\"no such manifest: \" + namedRef.String())}\n}\n\n// allEndpoints returns a list of endpoints ordered by priority (v2, http).\nfunc allEndpoints(ctx context.Context, namedRef reference.Named, insecure bool) ([]registry.APIEndpoint, error) {\n\tvar serviceOpts registry.ServiceOptions\n\tif insecure {\n\t\tlogrus.Debugf(\"allowing insecure registry for: %s\", reference.Domain(namedRef))\n\t\tserviceOpts.InsecureRegistries = []string{reference.Domain(namedRef)}\n\t}\n\tregistryService, err := registry.NewService(serviceOpts)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tendpoints, err := registryService.Endpoints(ctx, reference.Domain(namedRef))\n\tlogrus.Debugf(\"endpoints for %s: %v\", namedRef, endpoints)\n\treturn endpoints, err\n}\n","sourceCodeStart":256,"sourceCodeEnd":292,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/internal/registryclient/fetcher.go#L256-L292","documentation":"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.","triggerScenarios":"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>'.","commonSituations":"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.","solutions":["Verify the image reference is correct: check spelling of registry, repository, and tag with 'docker manifest inspect <image>'.","Ensure you are authenticated to the registry: run 'docker login <registry>' if using a private registry.","Check if the tag actually exists by browsing the registry UI or API.","If using a registry mirror, verify the mirror has the image or configure fallback to the upstream registry."],"exampleFix":"// before: generic error handling\nimg, err := fetcher.GetManifest(ctx, ref)\nif err != nil {\n    return err // 'no such manifest: myregistry.com/foo:bar'\n}\n\n// after: detect not-found specifically\nimg, err := fetcher.GetManifest(ctx, ref)\nif err != nil {\n    var nf notFoundError\n    if errors.As(err, &nf) {\n        return fmt.Errorf(\"image %s not found on any configured registry endpoint\", ref)\n    }\n    return err\n}","handlingStrategy":"validation","validationCode":"// Check image existence before deep operations\nfunc imageExists(ctx context.Context, cli *client.Client, ref string) bool {\n    _, _, err := cli.ImageInspectWithRaw(ctx, ref)\n    return err == nil || !client.IsErrNotFound(err)\n}","typeGuard":"// notFoundError implements NotFound() — use errors.As to detect\nfunc isManifestNotFound(err error) bool {\n    var nf notFoundError\n    return errors.As(err, &nf)\n}","tryCatchPattern":"manifest, err := fetcher.GetManifest(ctx, namedRef)\nif err != nil {\n    var nf notFoundError\n    if errors.As(err, &nf) {\n        return fmt.Errorf(\"image %s does not exist on any registry endpoint\", namedRef)\n    }\n    return err\n}","preventionTips":["Verify image references exist with 'docker manifest inspect <image>' before programmatic operations.","Ensure you are authenticated to private registries with 'docker login' before fetching manifests.","Use errors.As with notFoundError to distinguish 'not found' from network errors.","Double-check image name, tag, and registry spelling before fetching."],"tags":["registry","manifest","not-found","oci"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}