{"record":{"id":"24537c2cfaa32ac0","repo":"hashicorp/nomad","slug":"unable-to-pull-infra-docker-image-q-w","errorCode":null,"errorMessage":"unable to pull infra docker image %q: %w","messagePattern":"unable to pull infra docker image %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"drivers/docker/network.go","lineNumber":189,"sourceCode":"\t\t\t// Set the network mode to none which creates a network namespace\n\t\t\t// with only a loopback interface.\n\t\t\tNetworkMode: \"none\",\n\n\t\t\t// Set the restart policy to unless-stopped. The pause container should\n\t\t\t// never not be running until Nomad issues a stop.\n\t\t\t//\n\t\t\t// https://docs.docker.com/engine/reference/run/#restart-policies---restart\n\t\t\tRestartPolicy: containerapi.RestartPolicy{Name: containerapi.RestartPolicyUnlessStopped},\n\t\t},\n\t}, nil\n}\n\n// pullInfraImage conditionally pulls the `infra_image` from the Docker registry\n// only if its name uses the \"latest\" tag or the image doesn't already exist locally.\nfunc (d *Driver) pullInfraImage(allocID string) error {\n\trepo, tag, err := parseDockerImage(d.config.InfraImage)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"unable to pull infra docker image %q: %w\", d.config.InfraImage, err)\n\t}\n\n\tdockerClient, err := d.getDockerClient()\n\tif err != nil {\n\t\treturn err\n\t}\n\n\t// There's a (narrow) time-of-check-time-of-use race here. If we call\n\t// InspectImage and then a concurrent task shutdown happens before we call\n\t// IncrementImageReference, we could end up removing the image, and it\n\t// would no longer exist by the time we get to PullImage below.\n\td.coordinator.imageLock.Lock()\n\n\tif tag != \"latest\" {\n\t\tdockerImage, err := dockerClient.ImageInspect(d.ctx, d.config.InfraImage)\n\t\tif err != nil {\n\t\t\td.logger.Debug(\"InspectImage failed for infra_image container pull\",\n\t\t\t\t\"image\", d.config.InfraImage, \"error\", err)","sourceCodeStart":171,"sourceCodeEnd":207,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/drivers/docker/network.go#L171-L207","documentation":"pullInfraImage parses the configured infra_image into repo:tag before pulling. If parseDockerImage cannot parse the configured image reference, the error is wrapped as 'unable to pull infra docker image'. This check happens before any registry contact, so the failure is about the image reference format, not the pull itself.","triggerScenarios":"Driver option 'infra_image' is set to a value parseDockerImage rejects (empty reference, invalid characters, malformed tag/digest), and CreateNetwork invokes pullInfraImage for an allocation needing a bridge network.","commonSituations":"Typo in infra_image in the client block (e.g. missing repository name, stray spaces); copying an image reference with quotes or variables unresolved; invalid registry port syntax like 'registry:5000:' with empty tag.","solutions":["Fix the infra_image value in the client config to a valid image reference, e.g. 'busybox:latest'","Ensure the reference includes a parseable repo and optional tag/digest","Check for unexpanded environment variables or stray quotes in the config","Restart the Nomad client after correcting the configuration"],"exampleFix":"// before\ninfra_image = \"myinfra:\"\n// after\ninfra_image = \"myinfra:latest\"","handlingStrategy":"validation","validationCode":"func validImageRef(ref string) error {\n    if ref == \"\" { return errors.New(\"infra_image empty\") }\n    if _, _, err := reference.ParseAnyReference(ref); err != nil {\n        return fmt.Errorf(\"invalid infra_image %q: %w\", ref, err)\n    }\n    return nil\n}\n// run at client startup, before allocations arrive","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate infra_image in config management before shipping to clients","Always include repo and tag (e.g. busybox:1.36)","Avoid unexpanded template variables in image references","Smoke-test client config changes on one node first"],"tags":["docker","config","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"}