What causes "the image does not exist: %v" in hashicorp/nomad?

Run `docker images` on the client host to confirm the image and tag exist on the daemon.

the image does not exist: %v

Error message

the image does not exist: %v

What it means

convertAllocPathsForWindowsLCOW inspects the pulled image via dockerClient.ImageInspect to determine the image OS for Linux-Containers-on-Windows path rewriting. This error means the inspect call failed — practically, the image ID/reference is not present in the Docker daemon. It is raised in StartTask after the image was supposed to be created.

Source

Thrown at drivers/docker/driver.go:751

	}

	d.coordinator.IncrementImageReference(dockerImage.ID, driverConfig.Image, task.ID)
	var imageUser string
	if dockerImage.Config != nil {
		imageUser = dockerImage.Config.User
	}
	return dockerImage.ID, imageUser, nil
}

func (d *Driver) convertAllocPathsForWindowsLCOW(task *drivers.TaskConfig, image string) error {
	dockerClient, err := d.getDockerClient()
	if err != nil {
		return err
	}

	imageConfig, err := dockerClient.ImageInspect(d.ctx, image)
	if err != nil {
		return fmt.Errorf("the image does not exist: %v", err)
	}
	// LCOW If we are running a Linux Container on Windows, we need to mount it correctly, as c:\ does not exist on unix
	if imageConfig.Os == "linux" {
		a := []rune(task.Env[taskenv.AllocDir])
		task.Env[taskenv.AllocDir] = strings.ReplaceAll(string(a[2:]), "\\", "/")
		l := []rune(task.Env[taskenv.TaskLocalDir])
		task.Env[taskenv.TaskLocalDir] = strings.ReplaceAll(string(l[2:]), "\\", "/")
		s := []rune(task.Env[taskenv.SecretsDir])
		task.Env[taskenv.SecretsDir] = strings.ReplaceAll(string(s[2:]), "\\", "/")
	}
	return nil
}

func (d *Driver) containerBinds(task *drivers.TaskConfig, driverConfig *TaskConfig) ([]string, error) {
	taskLocalBindVolume := driverConfig.VolumeDriver == ""
	if !d.config.Volumes.Enabled && !taskLocalBindVolume {
		return nil, fmt.Errorf("volumes are not enabled; cannot use volume driver %q", driverConfig.VolumeDriver)
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

Run `docker images` on the client host to confirm the image and tag exist on the daemon.
Check earlier logs for pull failures — fix the root pull error first.
Disable aggressive image GC/pruning on the client or pin images by digest.
Verify Docker daemon is healthy (`docker info`) and reachable.

Example fix

// before
image = "myapp:latest" // tag moved, image is <none>
// after
image = "myapp@sha256:abcdef..." // pin by digest

Defensive patterns

Strategy: try-catch

Validate before calling

// verify image exists before task start
out, err := exec.Command("docker", "image", "inspect", imageRef).Output()
if err != nil { /* image absent on daemon; force re-pull */ }

Try / catch

if err != nil {
	if strings.Contains(err.Error(), "the image does not exist") {
		// force pull / re-create image and retry StartTask once
	}
	return err
}

Prevention

Pin images by digest to survive tag moves
Avoid `docker system prune` on Nomad clients while allocations run
Monitor pull logs earlier in StartTask for root failures

When it happens

Trigger: ImageInspect fails for the resolved image — e.g. the pull failed but the error was swallowed earlier, the image was garbage-collected between pull and inspect, a dangling/none reference was passed, or the daemon reports a network/registry error during inspect.

Common situations: Windows (LCOW) setups where the pull silently failed, images pruned by 'docker system prune' during the race, wrong image tag resolved to an untagged (none) image, or Docker daemon connectivity issues.

Related errors

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/4a305436e17d91ad. Report an issue: GitHub.