{"record":{"id":"47b5a56fe28668fe","repo":"hashicorp/nomad","slug":"unable-to-pull-docker-image-q-w","errorCode":null,"errorMessage":"unable to pull docker image %q: %w","messagePattern":"unable to pull docker image %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"drivers/docker/coordinator.go","lineNumber":193,"sourceCode":"\t// Nomad).\n\tdelete(d.pullFutures, image)\n\n\t// If we are cleaning up, we increment the reference count on the image\n\tif err == nil && d.cleanup {\n\t\td.incrementImageReferenceImpl(id, image, callerID)\n\t}\n\n\treturn id, user, err\n}\n\n// pullImageImpl is the implementation of pulling an image.\nfunc (d *dockerCoordinator) pullImageImpl(imageID string, authOptions *registry.AuthConfig,\n\tpullTimeout, pullActivityTimeout time.Duration) (string, string, error) {\n\tdefer d.clearPullLogger(imageID)\n\t// Parse the repo and tag\n\trepo, tag, err := parseDockerImage(imageID)\n\tif err != nil {\n\t\treturn \"\", \"\", fmt.Errorf(\"unable to pull docker image %q: %w\", imageID, err)\n\t}\n\n\tpullCtx, cancel := context.WithTimeout(d.ctx, pullTimeout)\n\tpm := newImageProgressManager(imageID, cancel, pullActivityTimeout, d.handlePullInactivity,\n\t\td.handlePullProgressReport, d.handleSlowPullProgressReport)\n\tdefer pm.stop()\n\n\t// Attempt to pull the image\n\tvar auth registry.AuthConfig\n\tif authOptions != nil {\n\t\tauth = *authOptions\n\t}\n\n\tpullOptions := mclient.ImagePullOptions{RegistryAuth: auth.Auth}\n\treader, err := d.client.ImagePull(pullCtx, dockerImageRef(repo, tag), pullOptions)\n\n\tif errors.Is(err, context.DeadlineExceeded) {\n\t\td.logger.Error(\"timeout pulling container\", \"image_ref\", dockerImageRef(repo, tag))","sourceCodeStart":175,"sourceCodeEnd":211,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/drivers/docker/coordinator.go#L175-L211","documentation":"pullImageImpl first parses the image reference (repo/tag) before contacting the registry; a malformed reference is wrapped as \"unable to pull docker image %q\". Later pull failures with other causes are also wrapped by this same message via the pull flow, so it generally means the image could not be pulled, starting with reference parsing.","triggerScenarios":"Requesting a pull with an imageID like 'library/redis:' (empty tag), invalid characters/whitespace, or a reference parseDockerImage cannot split into repo:tag.","commonSituations":"Template mistakes in job spec 'image' field (double colons 'redis::7', trailing colon, spaces), missing registry prefix where required, or invalid digest format.","solutions":["Fix the image reference: use 'name:tag' or 'name@sha256:digest' with valid characters (lowercase repo, no spaces).","Add an explicit tag — avoid relying on implicit defaults or trailing colons.","If the parse is fine but the pull itself failed, read the wrapped cause: check registry reachability, auth credentials, and image existence.","Test the same reference locally with 'docker pull <ref>' to confirm it resolves."],"exampleFix":"// before (job HCL)\nconfig {\n  image = \"redis::7\"\n}\n// after\nconfig {\n  image = \"redis:7\"\n}","handlingStrategy":"validation","validationCode":"// Validate image reference before submitting the job\nok := regexp.MustCompile(`^[a-z0-9]+((\\.|_|__|-)[a-z0-9]+)*(:[0-9]+)?(/[a-z0-9]+((\\.|_|__|-)[a-z0-9]+)*)*(:[\\w][\\w.-]{0,127})?(@sha256:[a-f0-9]{64})?$`).MatchString(image)\nif !ok { return fmt.Errorf(\"invalid image reference %q\", image) }","typeGuard":null,"tryCatchPattern":"Catch the pull error and inspect the wrapped cause with errors.Unwrap/errors.Is before deciding to retry.","preventionTips":["Always specify explicit tags; never end a reference with ':' or use double colons.","Run 'docker pull <ref>' in CI against the same registry before deploying the job.","Use digests for immutable references in production."],"tags":["docker","image-pull","image-reference"],"backgroundTag":"invalid-image-reference","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"}