{"record":{"id":"dbd33de57b052c89","repo":"hashicorp/nomad","slug":"failed-to-pull-s-w","errorCode":null,"errorMessage":"Failed to pull `%s`: %w","messagePattern":"Failed to pull `(.+?)`: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"drivers/docker/coordinator.go","lineNumber":429,"sourceCode":"\nfunc (d *dockerCoordinator) handlePullProgressReport(image, msg string, _ time.Time) {\n\td.logger.Debug(\"image pull progress\", \"image_name\", image, \"message\", msg)\n}\n\nfunc (d *dockerCoordinator) handleSlowPullProgressReport(image, msg string, _ time.Time) {\n\td.emitEvent(image, fmt.Sprintf(\"Docker image pull progress: %s\", msg), map[string]string{\n\t\t\"image\": image,\n\t})\n}\n\n// recoverablePullError wraps the error gotten when trying to pull and image if\n// the error is recoverable.\nfunc recoverablePullError(err error, image string) error {\n\trecoverable := true\n\tif imageNotFoundMatcher.MatchString(err.Error()) {\n\t\trecoverable = false\n\t}\n\treturn structs.NewRecoverableError(fmt.Errorf(\"Failed to pull `%s`: %w\", image, err), recoverable)\n}\n","sourceCodeStart":411,"sourceCodeEnd":431,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/drivers/docker/coordinator.go#L411-L431","documentation":"recoverablePullError wraps any error from the Docker image pull as \"Failed to pull `<image>`\", marking it recoverable unless the error text matches the imageNotFoundMatcher (e.g. manifest unknown / not found), in which case retrying is pointless. Callers use the recoverable flag to decide whether to reschedule the allocation.","triggerScenarios":"Any pullImageImpl failure reaching this wrapper: registry unreachable, auth rejected, rate limited, network timeouts, or image truly nonexistent in the registry.","commonSituations":"Docker Hub rate limiting (429 toomanyrequests), missing/misconfigured registry auth for a private repo, wrong image name (typo causing 'not found' -> non-recoverable), corporate proxy blocking registry.default","solutions":["Read the wrapped cause: if 'not found'/'manifest unknown', fix the image name/tag — retrying will not help.","If recoverable (network/rate limit), configure registry auth (auth block or docker config) and check registry connectivity.","Add registry credentials for private repos or authenticated Hub pulls to avoid rate limits.","Verify DNS/proxy/firewall allows the node to reach the registry endpoint.","Retry later for transient 5xx/timeout causes; Nomad will reschedule recoverable failures."],"exampleFix":"// before (job HCL, private registry)\nconfig { image = \"mycorp/app:latest\" }\n// after\nconfig { image = \"mycorp/app:1.4.2\" }\nauth {\n  username = \"ci-user\"\n  password = \"...\"\n  server_address = \"https://registry.mycorp.example\"\n}","handlingStrategy":"try-catch","validationCode":"// Pre-check image exists before submit\ncli, _ := client.NewClientWithOpts(client.FromEnv)\nif _, err := cli.DistributionInspect(ctx, image, authToken); err != nil {\n    return fmt.Errorf(\"image %q not resolvable in registry: %w\", image, err)\n}","typeGuard":"func isNonRecoverablePull(err error) bool {\n    var re *structs.RecoverableError\n    if errors.As(err, &re) { return !re.IsRecoverable() }\n    return false\n}","tryCatchPattern":"err := pull(...)\nvar re *structs.RecoverableError\nif errors.As(err, &re) && !re.IsRecoverable() {\n    return fmt.Errorf(\"bad image name/tag, not retrying: %w\", err)\n}\n// otherwise backoff + retry","preventionTips":["Configure registry auth for private repos and authenticated Docker Hub pulls.","Pin concrete tags (not :latest) to avoid surprise not-found/manifest errors.","Monitor Docker Hub rate limits; add a mirror or paid plan.","Check structs.NewRecoverableError flag to decide retry vs fail-fast."],"tags":["docker","image-pull","registry","recoverable"],"backgroundTag":"image-pull-failed","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}