{"record":{"id":"f4f8b3df82df4d29","repo":"containerd/containerd","slug":"failed-to-resolve-image-w","errorCode":null,"errorMessage":"failed to resolve image: %w","messagePattern":"failed to resolve image: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/transfer/local/pull.go","lineNumber":62,"sourceCode":"\tdefer done(ctx)\n\n\tif tops.Progress != nil {\n\t\ttops.Progress(transfer.Progress{\n\t\t\tEvent: fmt.Sprintf(\"Resolving from %s\", ir),\n\t\t})\n\t}\n\n\tif ir, ok := ir.(transfer.ImageResolverOptionSetter); ok {\n\t\tir.SetResolverOptions(\n\t\t\ttransfer.WithConcurrentLayerFetchBuffer(ts.config.ConcurrentLayerFetchBuffer),\n\t\t\ttransfer.WithMaxConcurrentDownloads(ts.config.MaxConcurrentDownloads),\n\t\t\ttransfer.WithDownloadLimiter(ts.limiterD),\n\t\t)\n\t}\n\n\tname, desc, err := ir.Resolve(ctx)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to resolve image: %w\", err)\n\t}\n\tif desc.MediaType == images.MediaTypeDockerSchema1Manifest {\n\t\t// Explicitly call out schema 1 as deprecated and not supported\n\t\treturn fmt.Errorf(\"schema 1 image manifests are no longer supported: %w\", errdefs.ErrInvalidArgument)\n\t}\n\n\t// Verify image before pulling.\n\tfor vfName, vf := range ts.config.Verifiers {\n\t\tlogger := log.G(ctx).WithFields(log.Fields{\n\t\t\t\"name\":     name,\n\t\t\t\"digest\":   desc.Digest.String(),\n\t\t\t\"verifier\": vfName,\n\t\t})\n\t\tlogger.Debug(\"Verifying image pull\")\n\n\t\tjdg, err := vf.VerifyImage(ctx, name, desc)\n\t\tif err != nil {\n\t\t\tlogger.WithError(err).Error(\"No judgement received from verifier\")","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/containerd/containerd/blob/4246446a2bf7d03837b0244118d858799393bd80/core/transfer/local/pull.go#L44-L80","documentation":"Wraps the error from the image resolver's Resolve call at the start of a local pull. The resolver (registry referrer) could not resolve the image reference to a descriptor — the name is wrong, credentials failed, the registry is unreachable, or the manifest does not exist.","triggerScenarios":"Calling Transfer with a pull source whose reference cannot be resolved: nonexistent tag/digest, unauthorized access to a private registry, DNS/network failure to the registry, or TLS misconfiguration.","commonSituations":"Typo'd or non-existent image tag, pulling from a private registry without configured credentials (~/.docker/config.json or containerd hosts.toml), corporate proxy blocking the registry, expired token, or offline environment.","solutions":["Verify the image reference exists: run `ctr image pull <ref>` or `docker manifest inspect <ref>`","Check registry credentials/hosts.toml configuration for the mirror/host","Test network reachability and TLS to the registry (curl the /v2/ endpoint)","If resolution is transient (network flake), retry the transfer"],"exampleFix":"// before\nerr := ts.Transfer(ctx, pull.NewPuller(\"registry.example.com/img:lates\"), ...)\n// after\nerr := ts.Transfer(ctx, pull.NewPuller(\"registry.example.com/img:latest\"), ...) // fix tag typo","handlingStrategy":"retry","validationCode":"// pre-check the reference resolves before transfer\nrc, err := remote.Get(resolver, ref)\nif err != nil { /* reference or registry problem */ }","typeGuard":null,"tryCatchPattern":"err := ts.Transfer(ctx, puller, dest, cfg)\nif err != nil && strings.Contains(err.Error(), \"failed to resolve image\") {\n    if netErr := (net.Error)(nil); errors.As(err, &netErr) { /* transient: retry with backoff */ }\n    // else: fix reference/credentials\n}","preventionTips":["Validate image tags/digests before transfer","Keep hosts.toml and credential helpers current for private registries","Use `docker manifest inspect`/`ctr image pull` as a pre-flight"],"tags":["containerd","registry","image-resolve","pull"],"backgroundTag":"image-resolution-failed","analyzedSha":"4246446a2bf7d03837b0244118d858799393bd80","analyzedAt":"2026-09-02T00:14:43.053Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}