hashicorp/nomad · error

jar_path or class must be specified

Error message

jar_path or class must be specified

What it means

The Nomad java driver refuses to start a task when neither a jar_path nor a class is given in the driver task config. After decoding and validating the driver config, StartTask requires at least one of these fields so it knows what Java entry point to run (java -jar <jar> vs java <class>). It throws immediately, before attempting to locate the java binary.

Source

Thrown at drivers/java/driver.go:447

	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

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

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set 'class' (fully qualified main class, e.g. 'com.example.Main') or 'jar_path' (path inside the task dir) in the java driver task config.
2. If using artifact blocks, verify the downloaded jar name matches jar_path and that templates rendered non-empty values.
3. Run 'nomad job inspect' to confirm the driver config the client actually received contains jar_path or class.

Example fix

// before
  driver = "java"
  config {
    jvm_options = ["-Xmx256m"]
  }
// after
  driver = "java"
  config {
    jar_path    = "local/myapp.jar"
    jvm_options = ["-Xmx256m"]
  }

// validate the java driver task config before submitting/starting
func validateJavaCfg(cfg map[string]interface{}) error {
    cls, _ := cfg["class"].(string)
    jar, _ := cfg["jar_path"].(string)
    if strings.TrimSpace(cls) == "" && strings.TrimSpace(jar) == "" {
        return errors.New("java driver task requires either jar_path or class")
    }
    return nil
}

func hasEntryPoint(cfg map[string]interface{}) bool {
    cls, okCls := cfg["class"].(string)
    jar, okJar := cfg["jar_path"].(string)
    return (okCls && strings.TrimSpace(cls) != "") || (okJar && strings.TrimSpace(jar) != "")
}

When it happens

Trigger: Calling StartTask (or submitting a Nomad job using driver 'java') where the task's driver config omits both 'jar_path' and 'class' — e.g. an empty/blank task block with only driver_args, jvm_options, or resource settings.

Common situations: Job files where the java stanza was deleted or renamed; templating that rendered the class/jar_path field empty; copying a task config from another driver (e.g. exec) that doesn't use these fields; typo'd field names so HCL decodes to zero values.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• default_pid_mode must be %q or %q, got %q
• default_ipc_mode must be %q or %q, got %q
• allow_caps configured with capabilities not supported by sys
• pid_mode must be %q or %q, got %q
• ipc_mode must be %q or %q, got %q

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