hashicorp/nomad · error

failed to decode driver config: %v

Error message

failed to decode driver config: %v

What it means

StartTask decodes the driver-specific task configuration block from the TaskConfig via cfg.DecodeDriverConfig into a TaskConfig struct. This error wraps whatever decoding failure occurred (wrong types, unknown fields with strict decoding, malformed hcl/job spec). It means the task's driver config could not be converted into the Docker driver's expected schema.

Source

Thrown at drivers/docker/driver.go:338

func loggingIsEnabled(driverCfg *DriverConfig, taskCfg *drivers.TaskConfig) bool {
	if driverCfg.DisableLogCollection {
		return false
	}
	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)
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the wrapped inner error (%v) to identify the exact field/type mismatch and fix the task's driver config block accordingly
2. Validate the job spec locally (nomad job validate) before submission
3. Ensure the config block targets the docker driver schema: image must be a string, args/port_map/auth fields must match TaskConfig types
4. If upgrading Nomad, check for removed/renamed docker driver config fields and update the job file

Example fix

// before (job spec)
config {
  image = 42          // wrong type
  args   = "foo"      // wrong type: must be a list
}
// after
config {
  image = "nginx:1.25"
  args   = ["foo"]
}

// validate driver config before submission
// $ nomad job validate job.nomad
// or programmatically ensure the config block matches docker driver schema:
if cfg["image"] == nil || reflect.TypeOf(cfg["image"]).Kind() != reflect.String {
    return errors.New("docker config.image must be a string")
}

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

if _, _, err := driver.StartTask(cfg); err != nil {
    if strings.HasPrefix(err.Error(), "failed to decode driver config") {
        // log wrapped cause, fix the task's config block; retry is futile without change
        return fmt.Errorf("invalid docker driver config: %w", err)
    }
    return err
}

When it happens

Trigger: Submitting a job whose docker driver 'config' block does not conform to TaskConfig (e.g. image given as a non-string, port_map with wrong type, args as a string instead of list) so DecodeDriverConfig returns an error, which StartTask wraps verbatim.

Common situations: Typo or wrong type in a Nomad job HCL/JSON docker config stanza; passing config produced for another driver (e.g. exec) to the docker driver; API/tooling generating JSON job specs with wrong field types; schema changes across Nomad versions making old fields invalid.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

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/a28591d19c381a02. Report an issue: GitHub.