{"record":{"id":"505866f30020fbfa","repo":"hashicorp/nomad","slug":"failed-to-decode-driver-config-v-505866","errorCode":null,"errorMessage":"failed to decode driver config: %v","messagePattern":"failed to decode driver config: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"drivers/java/driver.go","lineNumber":439,"sourceCode":"\t\tstartedAt:    taskState.StartedAt,\n\t\texitResult:   &drivers.ExitResult{},\n\t\tlogger:       d.logger,\n\t}\n\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 driverConfig.Class == \"\" && driverConfig.JarPath == \"\" {\n\t\treturn nil, nil, fmt.Errorf(\"jar_path or class must be specified\")\n\t}\n\n\tabsPath, err := GetAbsolutePath(\"java\")\n\tif err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"failed to find java binary: %s\", err)\n\t}\n\n\targs := javaCmdArgs(driverConfig)\n\n\td.logger.Info(\"starting java task\", \"driver_cfg\", hclog.Fmt(\"%+v\", driverConfig), \"args\", args)","sourceCodeStart":421,"sourceCodeEnd":457,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/drivers/java/driver.go#L421-L457","documentation":"This error is returned by StartTask when cfg.DecodeDriverConfig(&driverConfig) fails to decode the opaque driver-specific config map into the Java driver's TaskConfig struct. The task config's driver field data could not be unmarshaled (type mismatches, malformed values, unknown incompatible data). The task cannot start without a valid driver config.","triggerScenarios":"The job's task config block for driver 'java' contains values that cannot be decoded into TaskConfig fields (e.g. a string where []string is expected), or a NilVal/encoding error in the hcl/attrs decoding.","commonSituations":"Typo'd or wrong-typed job spec fields (class_extras as string vs list); jobs written for a different driver (e.g. docker config under java); Nomad/job-spec version mismatches.","solutions":["Fix the types and field names in the task's config block to match the Java driver schema (jar_path, class, class_extras, jvm_options, args, jvm_env_vars, work_dir, cap_add/cap_drop)","Validate the job with 'nomad job validate' before submitting","Ensure the job is written for the java driver, not another driver's config schema","Upgrade/downgrade Nomad if the config schema changed between versions"],"exampleFix":"// before (HCL)\nconfig {\n  jvm_options = \"-Xmx512m\"        # wrong: must be a list\n}\n// after\nconfig {\n  jvm_options = [\"-Xmx512m\"]\n}","handlingStrategy":"validation","validationCode":"// validate the job spec before submitting\n// nomad job validate job.nomad.hcl\n// in Go, ensure config values match TaskConfig types:\nvar tc java.TaskConfig\nif err := mapstructure.WeakDecode(rawCfg, &tc); err != nil {\n    return fmt.Errorf(\"invalid java driver config: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"if _, _, err := driver.StartTask(cfg); err != nil {\n    if strings.Contains(err.Error(), \"failed to decode driver config\") {\n        return fmt.Errorf(\"fix task config block types for driver 'java': %w\", err)\n    }\n}","preventionTips":["Run 'nomad job validate' in CI before submitting jobs","Match config field names and types exactly to the java driver schema","Do not reuse other drivers' config blocks under driver = \"java\"","Keep job specs aligned with the Nomad version in the cluster"],"tags":["nomad","java-driver","config-decode","job-spec"],"backgroundTag":"driver-config-decode-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"}