apache/dolphinscheduler · error · TaskException

Remote shell task error

Error message

Remote shell task error

What it means

RemoteExecutor.run executes the uploaded script remotely (upload, runRemote/track, getTaskExitCode) and wraps any failure in TaskException("Remote shell task error"). It covers every step of the remote execution lifecycle: script upload, command execution, tracking the process, and reading the final exit code.

Source

Thrown at dolphinscheduler-task-plugin/dolphinscheduler-task-remoteshell/src/main/java/org/apache/dolphinscheduler/plugin/task/remoteshell/RemoteExecutor.java:105

            throw new TaskException("SSH connection failed", e);
        }
        return session;
    }

    public int run(String taskId, String localFile) throws IOException {
        try {
            // only run task if no exist same task
            String pid = getTaskPid(taskId);
            if (StringUtils.isEmpty(pid)) {
                saveCommand(taskId, localFile);
                String runCommand = String.format(COMMAND.RUN_COMMAND, getRemoteShellHome(), taskId,
                        getRemoteShellHome(), taskId);
                runRemote(runCommand);
            }
            track(taskId);
            return getTaskExitCode(taskId);
        } catch (Exception e) {
            throw new TaskException("Remote shell task error", e);
        }
    }

    public void track(String taskId) throws Exception {
        int logN = 0;
        String pid;
        log.info("Remote shell task log:");
        TaskOutputParameterParser taskOutputParameterParser = new TaskOutputParameterParser();
        do {
            pid = getTaskPid(taskId);
            String trackCommand = String.format(COMMAND.TRACK_COMMAND, logN + 1, getRemoteShellHome(), taskId);
            int readLines = runRemoteAndProcessLines(trackCommand, line -> {
                log.info(line);
                taskOutputParameterParser.appendParseLog(line);
            });
            if (readLines > 0) {
                logN += readLines;

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Check the attached cause and worker logs to identify which phase failed (upload, run, track, exit-code read).
2. Ensure the remote home directory exists and the SSH user has write permission for it.
3. Verify remote disk space and file size limits for the uploaded script.
4. If the run hangs, check the remote machine's process (ps) and consider increasing or reviewing tracking timeouts.
5. Re-test with a trivial script (e.g., 'echo ok') to isolate connectivity vs script-content issues.

Example fix

// before: one opaque wrapper for all phases
throw new TaskException("Remote shell task error", e);
// after: phase-specific errors
try { remoteExecutor.uploadScript(...); } catch (Exception e) { throw new TaskException("Remote shell task error: upload failed", e); }
track(taskId);
return getTaskExitCode(taskId);

// before run: ensure remote home is writable
remoteExecutor.runRemote("mkdir -p " + remoteShellHome + " && df -h " + remoteShellHome);

try {
    int exit = remoteExecutor.run(taskId, localFile);
} catch (TaskException e) {
    logger.error("Remote shell failed at phase: {}", e.getCause(), e);
    // check upload vs run vs track per cause before retry
}

When it happens

Trigger: RemoteShellTask.handle() calls run(taskId, localFile) and any step throws: uploadScript fails, runRemote/track encounters an SSH error or timeout, or getTaskExitCode cannot read the remote exit status file.

Common situations: Remote home directory (remoteShellHome) missing or unwritable; script exceeds remote storage quota; SSH session drops mid-run; remote task hangs and tracking times out; missing exit-code file after process ends.

Related errors

• SSH connection failed
• Remote shell task error, exitStatus: ${exitStatus} error mes
• Execute shell task error
• cancel application error
• Cannot find the logic task factory: ${taskType}

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