hashicorp/nomad · error

failed to decode driver config: %v

Error message

failed to decode driver config: %v

What it means

StartTask could not decode the driver-specific TaskConfig out of the task's DriverConfig payload (cfg.DecodeDriverConfig). The job's driver config (e.g. command, args, cgroup fields) is not valid JSON matching the rawexec TaskConfig schema, or contains incompatible values/types.

Source

Thrown at drivers/rawexec/driver.go:402

			envList = append(envList, k+"="+v)
		}
	}
	sort.Strings(envList)
	return envList
}

func (d *Driver) StartTask(cfg *drivers.TaskConfig) (*drivers.TaskHandle, *drivers.DriverNetwork, error) {
	if !d.config.Enabled {
		return nil, nil, errDisabledDriver
	}

	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)
	}

	driverConfig.OverrideCgroupV2 = cgroupslib.CustomPathCG2(driverConfig.OverrideCgroupV2)

	if err := driverConfig.validate(); err != nil {
		return nil, nil, fmt.Errorf("failed driver config validation: %v", err)
	}

	if err := d.Validate(*cfg); err != nil {
		return nil, nil, fmt.Errorf("failed driver config validation: %v", err)
	}

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

	pluginLogFile := filepath.Join(cfg.TaskDir().Dir, "executor.out")
	executorConfig := &executor.ExecutorConfig{

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Validate the job with nomad job validate / nomad job run -output to see the decoded driver config
2. Compare your config block keys/types against the rawexec TaskConfig fields for your Nomad version (command, args, cgroup_v2, oom_score_adj, etc.)
3. Fix field names, types, and nesting in the job spec and resubmit
4. Upgrade/downgrade so job spec and Nomad agent versions agree

Example fix

// before (typo/type error in job hcl2)
config {
  comand = "/bin/sleep"
  args   = ["10"]
}
// after
config {
  command = "/bin/sleep"
  args    = ["10"]
}

// validate the job spec before submit
// $ nomad job validate job.nomad.hcl
// or programmatically:
if driverCfg, ok := taskConfig["rawexec"]; !ok {
  return errors.New("rawexec config block missing")
} else if _, ok := driverCfg["command"]; !ok {
  return errors.New("rawexec requires 'command'")
}

h, net, err := d.StartTask(cfg)
if err != nil && strings.Contains(err.Error(), "failed to decode driver config") {
  return fmt.Errorf("job spec rawexec config invalid: %w", err)
}

When it happens

Trigger: Submitting a job whose rawexec driver 'config' block does not unmarshal into drivers/rawexec TaskConfig — wrong field names/types, unknown required fields, or hcl2/template output producing an unexpected shape.

Common situations: Typo'd job config keys (e.g. 'comand' instead of 'command'); passing a string where a bool/int is expected; job written for a different driver or newer Nomad with fields this version lacks; programmatic job JSON with wrong nesting.

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 driver config validation: %v
• plugin not found
• wait config is nil or empty
• wait config is empty
• only one of cgroups_v1_override and cgroups_v2_override may

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