What causes "run java task error" in apache/dolphinscheduler?

Inspect the full stack trace and the shell task logs in the worker log; the real cause is the wrapped exception 'e'.

apache/dolphinscheduler · error · TaskException

run java task error

Error message

run java task error

What it means

JavaTask wraps any unexpected exception thrown while running the java task (either the java -jar or run-jar/class execution path) into a TaskException with the message 'run java task error'. It is the generic failure handler in JavaTask.handle(): when ShellCommandExecutor or the underlying java process fails with a non-InterruptedException, the exit status is set to failure and this exception propagates to the worker's task execution framework.

Source

Thrown at dolphinscheduler-task-plugin/dolphinscheduler-task-java/src/main/java/org/apache/dolphinscheduler/plugin/task/java/JavaTask.java:125

                    .appendScript(command);
            TaskResponse taskResponse = shellCommandExecutor.run(shellActuatorBuilder, taskCallBack);
            log.info("java task run result: {}", taskResponse);
            setExitStatusCode(taskResponse.getExitStatusCode());
            setAppIds(taskResponse.getAppIds());
            setProcessId(taskResponse.getProcessId());
            setTaskOutputParams(shellCommandExecutor.getTaskOutputParams());
        } catch (InterruptedException e) {
            log.error("java task interrupted ", e);
            setExitStatusCode(TaskConstants.EXIT_CODE_FAILURE);
            Thread.currentThread().interrupt();
        } catch (RunTypeNotFoundException e) {
            log.error(e.getMessage());
            setExitStatusCode(TaskConstants.EXIT_CODE_FAILURE);
            throw e;
        } catch (Exception e) {
            log.error("java task failed ", e);
            setExitStatusCode(TaskConstants.EXIT_CODE_FAILURE);
            throw new TaskException("run java task error", e);
        }
    }

    /**
     * Construct a shell command for the java -jar Run mode
     *
     * @return String
     **/
    protected String buildJarCommand() {
        ResourceContext resourceContext = taskRequest.getResourceContext();
        String mainJarAbsolutePathInLocal = resourceContext
                .getResourceItem(javaParameters.getMainJar().getResourceName())
                .getResourceAbsolutePathInLocal();
        StringBuilder builder = new StringBuilder();
        builder.append(getJavaCommandPath())
                .append(Constants.SPACE)
                .append(javaParameters.getJvmArgs().trim()).append(Constants.SPACE)
                .append(buildResourcePath()).append(Constants.SPACE)

View on GitHub (pinned to 02eac45a1b)

Solutions

Inspect the full stack trace and the shell task logs in the worker log; the real cause is the wrapped exception 'e'.
Verify the mainJar resource exists on the worker and the resource center downloaded it correctly.
Confirm java is installed and on PATH on the worker, with a compatible version for the jar.
Fix the task's java program type / main class / JVM args in the task definition.
If the jar itself fails, run it manually on the worker with the same command (shown in task logs) to reproduce.

Example fix

// before
} catch (Exception e) {
    throw new TaskException("run java task error", e);
}
// after
} catch (Exception e) {
    log.error("java task failed with exitCode {}", getExitStatusCode(), e);
    setExitStatusCode(TaskConstants.EXIT_CODE_FAILURE);
    throw new TaskException("run java task error: " + e.getMessage(), e);
}

Defensive patterns

Strategy: try-catch

Validate before calling

// preflight before scheduling the java task
File jar = new File(taskParams.getMainJar().getRes());
if (!jar.isFile()) throw new IllegalStateException("main jar missing: " + jar);
if (Runtime.getRuntime().exec(new String[]{"sh","-c","command -v java"}).waitFor() != 0)
    throw new IllegalStateException("java not on PATH");

Type guard

static boolean isTaskException(Throwable t) {
    return t instanceof TaskException;
}

Try / catch

try {
    javaTask.handle(callBack);
} catch (TaskException e) {
    log.error("java task failed, see cause for root reason", e);
    Throwable root = e.getCause();
    if (root instanceof InterruptedException) {
        Thread.currentThread().interrupt();
    }
}

Prevention

Validate the main jar resource exists and downloads correctly before execution.
Pin a compatible JDK on all worker images and keep it on PATH.
Run the jar manually with the exact logged command when triaging.
Keep JVM heap args within worker memory limits to avoid OOM kills.

When it happens

Trigger: JavaTask.handle() is invoked and the execution of the constructed shell command fails for any reason other than InterruptedException — e.g. ShellCommandExecutor.run throws, the java process exits abnormally, or any RuntimeException escapes the try block after the InterruptedException catch.

Common situations: Invalid java task parameters (main jar path wrong or resource not downloaded), java not found on the worker PATH, the jar throwing at runtime with a non-zero exit, JVM OOM, or filesystem permission problems when running the spawned java process.

Related errors

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/fe68bc93a39dddd0. Report an issue: GitHub.