hashicorp/nomad · error

failed driver config validation: %v

Error message

failed driver config validation: %v

What it means

After decoding, StartTask calls driverConfig.validate() to enforce the exec driver's constraints (e.g., allowed options like forgone caps, modes, cgroup values). A semantically invalid but decodable config produces this error and the task never launches.

Source

Thrown at drivers/exec/driver.go:469

	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)
	handle.Config = cfg

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

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the validation error detail to find the offending field and correct it in the job 'config' block.
2. Only request capabilities permitted by the client's allow_caps driver configuration.
3. Use valid isolation mode values (private/shared) for mode_pid/mode_ipc/mode_network.

Example fix

// before
config {
  command = "/bin/app"
  cap_add = ["NET_ADMIN"] // not in allow_caps
}
// after
config {
  command = "/bin/app"
  cap_add = ["NET_BIND_SERVICE"]
}

// pre-check capabilities against the client's allow list before submitting
allowed := map[string]bool{"NET_BIND_SERVICE": true, "IPC_LOCK": true}
for _, c := range requestedCaps {
    if !allowed[c] {
        return fmt.Errorf("capability %s not in driver allow_caps", c)
    }
}

When it happens

Trigger: TaskConfig fields pass decode but violate validation rules: unsupported capability in cap_add, invalid mode_pids/mode_ipc values, disallowed cgroups_v2 settings, or empty command.

Common situations: Requesting capabilities outside the driver's allowed set; typo'd isolation mode strings; config that was valid on an older/newer driver version.

Related errors

• allow_caps configured with capabilities not supported by sys
• cap_add configured with capabilities not supported by system
• cap_drop configured with capabilities not supported by syste
• allow_caps configured with capabilities not supported by sys
• failed to parse config:

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