hashicorp/nomad · error

failed to find java binary: %s

Error message

failed to find java binary: %s

What it means

StartTask calls GetAbsolutePath("java") to resolve the java executable on the client host's PATH. If java cannot be found, the driver cannot launch the JVM and wraps the lookup error with this message. It indicates the Nomad client environment lacks a usable Java runtime.

Source

Thrown at drivers/java/driver.go:452

		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",
		FSIsolation: driverCapabilities.FSIsolation == fsisolation.Chroot,
		Compute:     d.nomadConfig.Topology.Compute(),
	}

	user := cfg.User

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Install a JRE/JDK on the Nomad client host and confirm 'java -version' works as the user the nomad agent runs as.
2. Ensure java is on the PATH of the Nomad agent process (systemd: set Environment=PATH=... or use an absolute java path via the image).
3. If running with containers/chroot, make sure java is inside the chroot/image used for the task.
4. Restart the Nomad agent after installing Java so the updated PATH is picked up.

Example fix

# before: task fails with 'failed to find java binary: exec: "java": executable file not found in $PATH'
# after (Debian/Ubuntu client)
sudo apt-get install -y openjdk-17-jre-headless
# then verify as the nomad agent user
sudo -u nomad java -version

// shell check to run on every Nomad client before scheduling java tasks
if ! command -v java >/dev/null 2>&1; then
  echo "java binary not found on Nomad client PATH" >&2
  exit 1
fi
java -version || exit 1

h, _, err := driver.StartTask(cfg)
if err != nil && strings.Contains(err.Error(), "failed to find java binary") {
    return fmt.Errorf("install a JRE/JDK on the client and ensure 'java' is on the nomad agent's PATH: %w", err)
}

When it happens

Trigger: Starting a java-driver task on a Nomad client where the 'java' binary is not installed, not on the client's PATH, not in the driver's plugin_dir/allowed binaries, or exists but is not executable.

Common situations: Fresh clients provisioned without a JRE/JDK; images where Java was installed for a different user than the Nomad agent runs as; PATH differences between interactive shells and the Nomad service (systemd scrubbing PATH); fat JRE images vs slim ones; upgrading the OS and dropping /usr/bin/java.

Related errors

• init of plugin %s failed: %w
• 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

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