apache/dolphinscheduler · error · TaskException

Execute shell task error

Error message

Execute shell task error

What it means

RemoteShellTask.handle wraps any failure of the remote execution pipeline (uploading the script, remoteExecutor.run, dealOutParam) into TaskException("Execute shell task error") and sets exit status to failure. The cause exception carries the underlying reason (often one of the RemoteExecutor errors above).

Source

Thrown at dolphinscheduler-task-plugin/dolphinscheduler-task-remoteshell/src/main/java/org/apache/dolphinscheduler/plugin/task/remoteshell/RemoteShellTask.java:107

        setAppIds(taskId);
        taskExecutionContext.setAppIds(taskId);

        initRemoteExecutor();
    }

    @Override
    public void handle(TaskCallBack taskCallBack) throws TaskException {
        // add task close method to release resource
        try (RemoteExecutor executor = remoteExecutor) {
            // construct process
            String localFile = buildCommand();
            int exitCode = remoteExecutor.run(taskId, localFile);
            setExitStatusCode(exitCode);
            remoteShellParameters.dealOutParam(remoteExecutor.getTaskOutputParams());
        } 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 {
            log.info("kill remote task {}", taskId);
            remoteExecutor.kill(taskId);
        } catch (Exception e) {
            throw new TaskException("cancel application error", e);
        }
    }

    /**
     * create command
     *
     * @return file name

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Inspect the logged 'shell task error' stack trace for the underlying RemoteExecutor cause.
2. Verify SSH connectivity and credentials from the worker host to the remote machine.
3. Test the script content locally/remotely to rule out script errors before blaming the task framework.
4. Check localParams/varPool output definitions match what the script actually exports.

Example fix

// before: generic wrapper
throw new TaskException("Execute shell task error", e);
// after: include cause detail
throw new TaskException("Execute shell task error: " + e.getMessage(), e);

// pre-validate params and connectivity before handle()
if (!remoteShellParameters.checkParameters()) throw new IllegalStateException("bad params");
// ssh probe
new Socket().connect(new InetSocketAddress(host, port), 5000);

try {
    remoteShellTask.handle();
} catch (TaskException e) {
    logger.error("Remote shell task failed, root cause: {}", e.getCause() != null ? e.getCause().toString() : "n/a", e);
    setExitStatus(FAILURE); // match framework behavior
}

When it happens

Trigger: handle() is invoked and remoteExecutor.run(taskId, localFile) throws (SSH failure, remote non-zero exit, tracking failure) or remoteShellParameters.dealOutParam(...) throws while processing output params.

Common situations: SSH connectivity problems from worker; remote script fails; local temp script file cannot be written/read; output-parameter (varPool) mapping references invalid keys.

Related errors

• Remote shell task error
• Cannot find the logic task factory: ${taskType}
• The default branch is empty, please check the switch task co
• "Dispatch task: " + taskExecution.getName() + " to executor
• Execute task failed

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