{"record":{"id":"637c65908a4fc2c5","repo":"apache/dolphinscheduler","slug":"remote-shell-task-error","errorCode":null,"errorMessage":"Remote shell task error","messagePattern":"Remote shell task error","errorType":"exception","errorClass":"TaskException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-task-plugin/dolphinscheduler-task-remoteshell/src/main/java/org/apache/dolphinscheduler/plugin/task/remoteshell/RemoteExecutor.java","lineNumber":105,"sourceCode":"            throw new TaskException(\"SSH connection failed\", e);\n        }\n        return session;\n    }\n\n    public int run(String taskId, String localFile) throws IOException {\n        try {\n            // only run task if no exist same task\n            String pid = getTaskPid(taskId);\n            if (StringUtils.isEmpty(pid)) {\n                saveCommand(taskId, localFile);\n                String runCommand = String.format(COMMAND.RUN_COMMAND, getRemoteShellHome(), taskId,\n                        getRemoteShellHome(), taskId);\n                runRemote(runCommand);\n            }\n            track(taskId);\n            return getTaskExitCode(taskId);\n        } catch (Exception e) {\n            throw new TaskException(\"Remote shell task error\", e);\n        }\n    }\n\n    public void track(String taskId) throws Exception {\n        int logN = 0;\n        String pid;\n        log.info(\"Remote shell task log:\");\n        TaskOutputParameterParser taskOutputParameterParser = new TaskOutputParameterParser();\n        do {\n            pid = getTaskPid(taskId);\n            String trackCommand = String.format(COMMAND.TRACK_COMMAND, logN + 1, getRemoteShellHome(), taskId);\n            int readLines = runRemoteAndProcessLines(trackCommand, line -> {\n                log.info(line);\n                taskOutputParameterParser.appendParseLog(line);\n            });\n            if (readLines > 0) {\n                logN += readLines;\n","sourceCodeStart":87,"sourceCodeEnd":123,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-task-plugin/dolphinscheduler-task-remoteshell/src/main/java/org/apache/dolphinscheduler/plugin/task/remoteshell/RemoteExecutor.java#L87-L123","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the attached cause and worker logs to identify which phase failed (upload, run, track, exit-code read).","Ensure the remote home directory exists and the SSH user has write permission for it.","Verify remote disk space and file size limits for the uploaded script.","If the run hangs, check the remote machine's process (ps) and consider increasing or reviewing tracking timeouts.","Re-test with a trivial script (e.g., 'echo ok') to isolate connectivity vs script-content issues."],"exampleFix":"// before: one opaque wrapper for all phases\nthrow new TaskException(\"Remote shell task error\", e);\n// after: phase-specific errors\ntry { remoteExecutor.uploadScript(...); } catch (Exception e) { throw new TaskException(\"Remote shell task error: upload failed\", e); }\ntrack(taskId);\nreturn getTaskExitCode(taskId);","handlingStrategy":"try-catch","validationCode":"// before run: ensure remote home is writable\nremoteExecutor.runRemote(\"mkdir -p \" + remoteShellHome + \" && df -h \" + remoteShellHome);","typeGuard":null,"tryCatchPattern":"try {\n    int exit = remoteExecutor.run(taskId, localFile);\n} catch (TaskException e) {\n    logger.error(\"Remote shell failed at phase: {}\", e.getCause(), e);\n    // check upload vs run vs track per cause before retry\n}","preventionTips":["Verify remoteShellHome exists and is writable by the SSH user before running tasks.","Monitor remote host disk space for uploaded scripts.","Smoke-test connectivity with 'echo ok' scripts during environment setup."],"tags":["remote-execution","ssh","shell-script","task-execution"],"backgroundTag":"remote-command-failed","analyzedSha":"02eac45a1b6676e639fcbfb4be2243de5771b05d","analyzedAt":"2026-09-06T17:43:00.555Z","contentChangedAt":"2026-09-06T17:43:00.555Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}