hashicorp/nomad · error

failed driver config validation: %v

Error message

failed driver config validation: %v

What it means

This error is returned by StartTask when the decoded TaskConfig fails driverConfig.validate(). Any of the driver's validation rules failed - for the Java driver this includes unsupported cap_add/cap_drop capabilities and a relative work_dir - and the underlying validation error is wrapped and returned. The task config is accepted at the API layer but invalid for this driver.

Source

Thrown at drivers/java/driver.go:443

	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)

	handle = drivers.NewTaskHandle(taskHandleVersion)
	handle.Config = cfg

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the wrapped inner error to see which validation rule failed and fix that field
2. Use 'nomad job validate' (which runs driver validation) before submitting the job
3. Correct cap_add/cap_drop to the host's supported capabilities and make work_dir absolute
4. Test the same job spec against the target client's driver with nomad node status / eval

Example fix

// before (HCL)
config {
  class = "com.example.Main"
  work_dir = "relative/dir"
}
// after
config {
  class = "com.example.Main"
  work_dir = "/opt/app/relative/dir"
}

// pre-validate the java task config as the driver does
import "github.com/hashicorp/nomad/client/lib/capabilities"

func validJavaCfg(tc java.TaskConfig) error {
    supported := capabilities.Supported()
    if !supported.Difference(capabilities.New(tc.CapAdd)).Empty() { return errors.New("bad cap_add") }
    if !supported.Difference(capabilities.New(tc.CapDrop)).Empty() { return errors.New("bad cap_drop") }
    if tc.WorkDir != "" && !filepath.IsAbs(tc.WorkDir) { return errors.New("relative work_dir") }
    return nil
}

if _, _, err := driver.StartTask(cfg); err != nil {
    if strings.Contains(err.Error(), "failed driver config validation") {
        // inspect the wrapped cause and fix the offending field
        return fmt.Errorf("java driver validation: %w", err)
    }
}

When it happens

Trigger: Starting a Java task whose config violates validate(): unsupported capability in cap_add/cap_drop, or work_dir set to a non-absolute path.

Common situations: Capability lists referencing unsupported/misspelled capabilities; relative work_dir paths; configs validated on one host class but scheduled on another with fewer kernel capabilities.

Related errors

• wait config is nil or empty
• missing datacenter for client registration
• default_identity_ttl must be greater than 0
• max_identity_ttl must be greater than 0
• max_identity_ttl must be greater than or equal to default_id

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