hashicorp/nomad · error

failed to decode driver config: %v

Error message

failed to decode driver config: %v

What it means

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.

Source

Thrown at drivers/java/driver.go:439

		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 driverConfig.Class == "" && driverConfig.JarPath == "" {
		return nil, nil, fmt.Errorf("jar_path or class must be specified")
	}

	absPath, err := GetAbsolutePath("java")
	if err != nil {
		return nil, nil, fmt.Errorf("failed to find java binary: %s", err)
	}

	args := javaCmdArgs(driverConfig)

	d.logger.Info("starting java task", "driver_cfg", hclog.Fmt("%+v", driverConfig), "args", args)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. 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)
2. Validate the job with 'nomad job validate' before submitting
3. Ensure the job is written for the java driver, not another driver's config schema
4. Upgrade/downgrade Nomad if the config schema changed between versions

Example fix

// before (HCL)
config {
  jvm_options = "-Xmx512m"        # wrong: must be a list
}
// after
config {
  jvm_options = ["-Xmx512m"]
}

// validate the job spec before submitting
// nomad job validate job.nomad.hcl
// in Go, ensure config values match TaskConfig types:
var tc java.TaskConfig
if err := mapstructure.WeakDecode(rawCfg, &tc); err != nil {
    return fmt.Errorf("invalid java driver config: %w", err)
}

if _, _, err := driver.StartTask(cfg); err != nil {
    if strings.Contains(err.Error(), "failed to decode driver config") {
        return fmt.Errorf("fix task config block types for driver 'java': %w", err)
    }
}

When it happens

Trigger: 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.

Common situations: 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.

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
• pid_mode must be %q or %q, got %q
• ipc_mode must be %q or %q, got %q
• failed to decode driver config: %v
• envoy must be used as connect sidecar or gateway

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