hashicorp/nomad · error

failed to decode driver config: %v

Error message

failed to decode driver config: %v

What it means

StartTask decodes the opaque driver configuration map from the TaskConfig into the exec driver's TaskConfig struct via cfg.DecodeDriverConfig. If the payload cannot be decoded (wrong types, unknown/invalid fields, malformed hcl/json), the task is not started. This surfaces misconfiguration between the job spec and the driver schema.

Source

Thrown at drivers/exec/driver.go:465

		startedAt:    taskState.StartedAt,
		exitResult:   &drivers.ExitResult{},
		logger:       d.logger,
	}

	d.tasks.Set(taskState.TaskConfig.ID, h)

	go h.run()
	return nil
}

func (d *Driver) StartTask(cfg *drivers.TaskConfig) (handle *drivers.TaskHandle, network *drivers.DriverNetwork, err 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 err := driverConfig.validate(); err != nil {
		return nil, nil, fmt.Errorf("failed driver config validation: %v", err)
	}

	if cfg.User == "" {
		cfg.User = "nobody"
	}

	d.logger.Debug("setting up user", "user", cfg.User)

	if err := d.userIDValidator.HasValidIDs(cfg.User); err != nil {
		return nil, nil, fmt.Errorf("failed host user validation: %v", err)
	}

	d.logger.Info("starting task", "driver_cfg", hclog.Fmt("%+v", driverConfig))
	handle = drivers.NewTaskHandle(taskHandleVersion)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Fix the driver 'config' block in the job spec so keys and value types match the exec driver's TaskConfig schema.
2. Run 'nomad job validate' / 'nomad plan' to catch schema mismatches before submission.
3. Ensure client and server Nomad versions are compatible for the driver options used.

Example fix

// before (job config)
config {
  command = "/bin/sleep"
  args    = ["1"]
  caps    = true // unknown/wrong-typed option
}
// after
config {
  command = "/bin/sleep"
  args    = ["1"]
}

// validate the job (and its driver config) before submission
// $ nomad job validate job.nomad.hcl
// programmatically:
_, _, err := client.Jobs().Validate(job, nil)
if err != nil {
    return fmt.Errorf("job driver config invalid: %w", err)
}

When it happens

Trigger: Job spec exec driver options do not match the TaskConfig struct fields (e.g., non-boolean for a bool option, wrong nesting), or the encoded payload was produced by an incompatible Nomad version.

Common situations: Typo'd or mis-typed driver options in the job 'config' block; using raw_exec-style options with the exec driver; client and server Nomad versions out of sync so config schemas differ.

Understand the failure class

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

Related errors

• failed to decode driver config: %v
• failed to decode driver config: %v
• envoy must be used as connect sidecar or gateway
• Disconnect cannot be configured with both lost_after and sto
• lost_after cannot be a negative duration

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