{"record":{"id":"3e139b9db96074c2","repo":"hashicorp/nomad","slug":"failed-driver-config-validation-v","errorCode":null,"errorMessage":"failed driver config validation: %v","messagePattern":"failed driver config validation: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"drivers/exec/driver.go","lineNumber":469,"sourceCode":"\n\td.tasks.Set(taskState.TaskConfig.ID, h)\n\n\tgo h.run()\n\treturn nil\n}\n\nfunc (d *Driver) StartTask(cfg *drivers.TaskConfig) (handle *drivers.TaskHandle, network *drivers.DriverNetwork, err error) {\n\tif _, ok := d.tasks.Get(cfg.ID); ok {\n\t\treturn nil, nil, fmt.Errorf(\"task with ID %q already started\", cfg.ID)\n\t}\n\n\tvar driverConfig TaskConfig\n\tif err := cfg.DecodeDriverConfig(&driverConfig); err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"failed to decode driver config: %v\", err)\n\t}\n\n\tif err := driverConfig.validate(); err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"failed driver config validation: %v\", err)\n\t}\n\n\tif cfg.User == \"\" {\n\t\tcfg.User = \"nobody\"\n\t}\n\n\td.logger.Debug(\"setting up user\", \"user\", cfg.User)\n\n\tif err := d.userIDValidator.HasValidIDs(cfg.User); err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"failed host user validation: %v\", err)\n\t}\n\n\td.logger.Info(\"starting task\", \"driver_cfg\", hclog.Fmt(\"%+v\", driverConfig))\n\thandle = drivers.NewTaskHandle(taskHandleVersion)\n\thandle.Config = cfg\n\n\tpluginLogFile := filepath.Join(cfg.TaskDir().Dir, \"executor.out\")\n\texecutorConfig := &executor.ExecutorConfig{","sourceCodeStart":451,"sourceCodeEnd":487,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/drivers/exec/driver.go#L451-L487","documentation":"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.","triggerScenarios":"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.","commonSituations":"Requesting capabilities outside the driver's allowed set; typo'd isolation mode strings; config that was valid on an older/newer driver version.","solutions":["Read the validation error detail to find the offending field and correct it in the job 'config' block.","Only request capabilities permitted by the client's allow_caps driver configuration.","Use valid isolation mode values (private/shared) for mode_pid/mode_ipc/mode_network."],"exampleFix":"// before\nconfig {\n  command = \"/bin/app\"\n  cap_add = [\"NET_ADMIN\"] // not in allow_caps\n}\n// after\nconfig {\n  command = \"/bin/app\"\n  cap_add = [\"NET_BIND_SERVICE\"]\n}","handlingStrategy":"validation","validationCode":"// pre-check capabilities against the client's allow list before submitting\nallowed := map[string]bool{\"NET_BIND_SERVICE\": true, \"IPC_LOCK\": true}\nfor _, c := range requestedCaps {\n    if !allowed[c] {\n        return fmt.Errorf(\"capability %s not in driver allow_caps\", c)\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Cross-check cap_add/cap_drop against the client's driver allow_caps configuration.","Use only documented values for mode_pid/mode_ipc/mode_network (private|shared).","Test task configs in a dev Nomad cluster mirroring production driver settings."],"tags":["nomad","exec-driver","config-validation","capabilities"],"backgroundTag":"driver-config-validation-failed","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}