apache/dolphinscheduler · critical · TaskException

SSH connection failed

Error message

SSH connection failed

What it means

RemoteExecutor.getSession establishes an SSH session via SSHUtils.getSession; if the returned session is null or SSH authentication (session.auth().verify()) does not succeed, it throws TaskException("SSH connection failed") with no cause. This is the explicit no-cause variant indicating connection setup or auth verification failed.

Source

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

    public RemoteExecutor(SSHConnectionParam sshConnectionParam) {

        this.sshConnectionParam = sshConnectionParam;
        initClient();
    }

    private void initClient() {
        sshClient = SshClient.setUpDefaultClient();
        sshClient.start();
    }

    private ClientSession getSession() {
        if (session != null && session.isOpen()) {
            return session;
        }
        try {
            session = SSHUtils.getSession(sshClient, sshConnectionParam);
            if (session == null || !session.auth().verify().isSuccess()) {
                throw new TaskException("SSH connection failed");
            }
        } catch (Exception e) {
            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);

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Test SSH connectivity manually from the worker host: ssh <user>@<host> -p <port> using the same credentials/key.
2. Verify the RemoteShellParameters connection params (host, port, user, password/privateKey) are correct and complete.
3. If using a private key, confirm the key format is supported (OpenSSH vs PEM) and has no passphrase unless configured.
4. Check the SSH server config (sshd_config) for PasswordAuthentication/PublicKeyAuthentication settings matching your auth method.
5. Confirm firewall/network policy allows the worker to reach the target on the SSH port.

Example fix

// before (no detail about which check failed)
if (session == null || !session.auth().verify().isSuccess()) {
    throw new TaskException("SSH connection failed");
}
// after (distinguish null vs auth failure)
if (session == null) {
    throw new TaskException("SSH connection failed: could not connect to " + sshConnectionParam.getHost());
}
if (!session.auth().verify().isSuccess()) {
    throw new TaskException("SSH authentication failed for user " + sshConnectionParam.getUser());
}

// pre-flight from the worker host
boolean reachable = new Socket().connect(new InetSocketAddress(host, port), 5000);
// and: ssh -o BatchMode=yes -i keyfile user@host 'echo ok' must succeed

boolean validSshParam(RemoteShellParameters p) {
    return p != null && notBlank(p.getHost()) && p.getPort() > 0 && notBlank(p.getUser())
        && (notBlank(p.getPassword()) || notBlank(p.getPrivateKey()));
}

try {
    remoteExecutor.run(taskId, script);
} catch (TaskException e) {
    if (e.getMessage().contains("SSH connection failed")) {
        logger.error("SSH setup/auth failure — verify host, port, credentials");
    }
    throw e;
}

When it happens

Trigger: uploadScript() or runRemoteAndProcessLines() call getSession() and either SSHUtils.getSession returns null (connection could not be established) or the SSH auth result is not isSuccess().

Common situations: Wrong host/port in remote shell task params; wrong username/password or private key; SSH server rejects the auth method (password auth disabled); network/firewall blocking port 22; host key rejection.

Related errors

• OIDC_TOKEN_EXCHANGE_FAILED
• Remote shell task error
• cancel application error
• WorkflowInstance: %s pause failed
• WorkflowInstance: %s stop failed

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