What causes "Execute shell task error" in apache/dolphinscheduler?

Inspect the wrapped cause in the worker log (logged as 'shell task error') to identify the underlying IO or execution failure

apache/dolphinscheduler · error · TaskException

Execute shell task error

Error message

Execute shell task error

What it means

The generic catch-all in ShellTask.handle(): any non-interrupt exception while building or running the shell command (task-prepare failure, command IO errors, executor failures) is logged and rethrown as TaskException("Execute shell task error", e) with exit status EXIT_CODE_FAILURE. The root cause is in the wrapped exception.

Source

Thrown at dolphinscheduler-task-plugin/dolphinscheduler-task-shell/src/main/java/org/apache/dolphinscheduler/plugin/task/shell/ShellTask.java:81

        try {
            IShellInterceptorBuilder<?, ?> shellActuatorBuilder = ShellInterceptorBuilderFactory.newBuilder()
                    .properties(ParameterUtils.convert(taskRequest.getPrepareParamsMap()))
                    .appendScript(shellParameters.getRawScript());

            TaskResponse commandExecuteResult = shellCommandExecutor.run(shellActuatorBuilder, taskCallBack);
            setExitStatusCode(commandExecuteResult.getExitStatusCode());
            setProcessId(commandExecuteResult.getProcessId());
            shellParameters.dealOutParam(shellCommandExecutor.getTaskOutputParams());
            taskRequest.setVarPool(shellParameters.getVarPool());
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            log.error("The current Shell task has been interrupted", e);
            setExitStatusCode(EXIT_CODE_FAILURE);
            throw new TaskException("The current Shell task has been interrupted", e);
        } catch (Exception e) {
            log.error("shell task error", e);
            setExitStatusCode(EXIT_CODE_FAILURE);
            throw new TaskException("Execute shell task error", e);
        }
    }

    @Override
    public void cancel() throws TaskException {
        // cancel process
        try {
            shellCommandExecutor.cancelApplication();
        } catch (Exception e) {
            throw new TaskException("cancel application error", e);
        }
    }

    @Override
    public AbstractParameters getParameters() {
        return shellParameters;
    }

View on GitHub (pinned to 02eac45a1b)

Solutions

Inspect the wrapped cause in the worker log (logged as 'shell task error') to identify the underlying IO or execution failure
Verify the worker's exec path (config execPath/temp dir) exists and is writable by the worker OS user
Run the script's content manually on the worker host as the same user to reproduce the failure outside the scheduler

Example fix

// before: worker exec dir unwritable
execPath: /root/dolphinscheduler/exec
// after
execPath: /opt/dolphinscheduler/exec  # chown dolphinscheduler:dolphinscheduler, chmod 755

Defensive patterns

Strategy: try-catch

Validate before calling

// preflight on the worker host
cmd = "test -w " + execPath + " && df -h " + execPath

Try / catch

try {
    shellTask.handle(callBack);
} catch (TaskException e) {
    log.error("shell task failed", e.getCause()); // inspect wrapped cause
}

Prevention

Keep the worker exec/temp directories writable by the worker OS user and monitor free disk space
Include the worker user in your deployment checks
Always log/print the wrapped cause to find the real failure before changing config

When it happens

Trigger: ShellCommandExecutor.run() throws for any reason other than InterruptedException — e.g. failure creating the exec temp directory, writing the command file, or reading process output; the shell script exits and the executor itself throws.

Common situations: Worker run directory not writable or disk full so the generated .command file cannot be written; interpreter in the shebang missing on the worker; task output param collection failing after execution.

Related errors

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