hashicorp/nomad · error

image name required for docker driver

Error message

image name required for docker driver

What it means

The Docker driver requires an image name to run a container. After decoding the driver config, StartTask checks TaskConfig.Image and returns this error if it is empty, since a container cannot be created without a base image.

Source

Thrown at drivers/docker/driver.go:342

	if taskCfg.StderrPath == os.DevNull && taskCfg.StdoutPath == os.DevNull {
		return false
	}
	return true
}

func (d *Driver) StartTask(cfg *drivers.TaskConfig) (*drivers.TaskHandle, *drivers.DriverNetwork, error) {
	if _, ok := d.tasks.Get(cfg.ID); ok {
		return nil, nil, fmt.Errorf("task with ID %q already started", cfg.ID)
	}

	var driverConfig TaskConfig

	if err := cfg.DecodeDriverConfig(&driverConfig); err != nil {
		return nil, nil, fmt.Errorf("failed to decode driver config: %v", err)
	}

	if driverConfig.Image == "" {
		return nil, nil, fmt.Errorf("image name required for docker driver")
	}

	driverConfig.Image = strings.TrimPrefix(driverConfig.Image, "https://")

	driverConfig.ImagePullTimeout = getValue(driverConfig.ImagePullTimeout, d.config.ImagePullTimeout)

	handle := drivers.NewTaskHandle(taskHandleVersion)
	handle.Config = cfg

	// we'll need the normal docker client
	dockerClient, err := d.getDockerClient()
	if err != nil {
		return nil, nil, fmt.Errorf("Failed to create docker client: %v", err)
	}

	dockerInfo, err := dockerClient.Info(d.ctx, mclient.InfoOptions{})
	if err != nil {
		return nil, nil, fmt.Errorf("failed to fetch docker daemon info: %v", err)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Add an image field to the task's docker config block, e.g. image = "nginx:1.25"
2. If the image is templated, ensure the template variable resolves to a non-empty value before job submission
3. Run nomad job validate to catch the missing image before dispatch
4. If constructing jobs in code, set the Image field on the docker TaskConfig explicitly

Example fix

// before
task "web" {
  driver = "docker"
  config {
    # image line missing
    port_map { http = 80 }
  }
}
// after
task "web" {
  driver = "docker"
  config {
    image = "nginx:1.25"
    port_map { http = 80 }
  }
}

// pre-flight check before submit
if img, _ := cfg["image"].(string); img == "" {
    return errors.New("docker driver requires non-empty config.image")
}

func hasImage(cfg map[string]interface{}) bool {
    img, ok := cfg["image"].(string)
    return ok && strings.TrimSpace(img) != ""
}

if _, _, err := driver.StartTask(cfg); err != nil {
    if err.Error() == "image name required for docker driver" {
        return fmt.Errorf("task %q: add config { image = ... } to the docker task", cfg.ID)
    }
    return err
}

When it happens

Trigger: A docker task's driver config block omits the 'image' field entirely, or sets it to an empty string (image = ""), so driverConfig.Image == "" after DecodeDriverConfig.

Common situations: Hand-written job specs where the image line was deleted or commented out; templating tools rendering an empty image variable (e.g. ${image_version} unset); programmatic job construction that leaves TaskConfig.Image zero-valued; pasting a config from another driver (raw_exec/exec) that has no image field.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• failed to reattach to docker logger process: %v
• failed to launch docker logger plugin: %v
• failed to launch docker logger process %s: %v
• failed to get docker client: %w
• task with ID %q already started

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