{"record":{"id":"d12f6a2062d868e8","repo":"hashicorp/nomad","slug":"unable-to-create-local-docker-image-q-w","errorCode":null,"errorMessage":"unable to create local docker image %q: %w","messagePattern":"unable to create local docker image %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"drivers/docker/driver.go","lineNumber":625,"sourceCode":"\t\tif attempted < 5 {\n\t\t\tattempted++\n\t\t\tbackoff = helper.Backoff(50*time.Millisecond, time.Minute, attempted)\n\t\t\ttime.Sleep(backoff)\n\t\t\tgoto START\n\t\t}\n\t\treturn nstructs.NewRecoverableError(startErr, true)\n\t}\n\n\treturn recoverableErrTimeouts(startErr)\n}\n\n// createImage creates a docker image either by pulling it from a registry or by\n// loading it from the file system\nfunc (d *Driver) createImage(task *drivers.TaskConfig, driverConfig *TaskConfig, client *client.Client) (string, string, error) {\n\timage := driverConfig.Image\n\trepo, tag, err := parseDockerImage(image)\n\tif err != nil {\n\t\treturn \"\", \"\", fmt.Errorf(\"unable to create local docker image %q: %w\", image, err)\n\t}\n\n\t// We're going to check whether the image is already downloaded. If the tag\n\t// is \"latest\", or ForcePull is set, we have to check for a new version every time so we don't\n\t// bother to check and cache the id here. We'll download first, then cache.\n\tif driverConfig.ForcePull {\n\t\td.logger.Debug(\"force pulling image instead of inspecting local\", \"image_ref\", dockerImageRef(repo, tag))\n\t} else if tag != \"latest\" {\n\t\tif dockerImage, _ := client.ImageInspect(d.ctx, image); dockerImage.ID != \"\" {\n\t\t\t// Image exists so just increment its reference count\n\t\t\td.coordinator.IncrementImageReference(dockerImage.ID, image, task.ID)\n\t\t\tvar user string\n\t\t\tif dockerImage.Config != nil {\n\t\t\t\tuser = dockerImage.Config.User\n\t\t\t}\n\t\t\treturn dockerImage.ID, user, nil\n\t\t}\n\t}","sourceCodeStart":607,"sourceCodeEnd":643,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/drivers/docker/driver.go#L607-L643","documentation":"createImage wraps any failure from parseDockerImage when splitting the task's docker image into repository and tag. It means the image string itself could not be parsed into a valid repo:tag reference before any registry interaction. The wrapped error typically indicates a malformed image reference (e.g. invalid characters or empty name).","triggerScenarios":"driverConfig.Image contains a reference parseDockerImage rejects — e.g. an empty image string, invalid characters, or a ref that cannot be split into repo/tag. Raised synchronously in StartTask via createImage before any pull or load happens.","commonSituations":"Typos in the image field of the docker task driver config, template interpolation leaving image empty (e.g. missing variable), pasting a full 'docker pull' command line, or stray whitespace/quotes in the image name.","solutions":["Fix the image field in the task's driver config to a valid reference like 'nginx:1.25' or 'hashicorp/http-echo:0.2.1'.","Check that any template/variable interpolation used to build the image name actually resolves (no empty values).","If the image has no tag, add an explicit tag so parsing is unambiguous.","Inspect the wrapped error (%w) in the job logs for the exact parse failure."],"exampleFix":"// before\nconfig {\n  image = \"\"\n}\n// after\nconfig {\n  image = \"nginx:1.25\"\n}","handlingStrategy":"validation","validationCode":"func validImageRef(image string) bool {\n\tif image == \"\" { return false }\n\tparts := strings.Split(image, \":\")\n\tif len(parts) > 2 { return false }\n\tif !strings.ContainsAny(parts[0], \"/abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789.-_\") { return false }\n\treturn true\n}\n// call before submitting job: validImageRef(cfg.Image)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always specify image with an explicit tag","Validate job spec with `nomad job validate` before submission","Avoid template interpolation that can render an empty image"],"tags":["docker","config","image-parsing"],"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"}