---
schema_version: "1"
id: d42e15ca51c477c607697749197fc4e30ba3e8ee5609dfcf6d63b02adbe11033
title: Troubleshooting SFTP Connector
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/sftp-connector/latest/sftp-connector-troubleshooting.md
canonical_url: https://docs.mulesoft.com/sftp-connector/latest/sftp-connector-troubleshooting
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 79d648038bffa74b150451491802cdfa70a60de9ffd3bf285e74c73d445973d7
description: MuleSoft Documentation Site
release: "2.7"
latest: true
---
---
product: SFTP Connector
version: 2.7
is-latest-version: true
---

# Troubleshooting SFTP Connector

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

To troubleshoot Anypoint Connector for SFTP (SFTP Connector), become familiar with the information
about troubleshooting connectivity, permissions, and server-side issues, troubleshooting Mule
application issues, interpreting commonly thrown messages, and troubleshooting identity file format
issues.

## Troubleshoot Connectivity, Permissions and Server-Side Issues

Sometimes when attempting to connect to an SFTP server you can experience problems establishing the
connection because an SFTP server requires a configured encrypted communication channel. For
example, you might need to enable specific encryption cyphers or key exchange algorithms, or
indicate the location of certain authorization keys.

To resolve this issue:

1.  Locate the SFTP servers configuration file to review the parameters and settings regarding the
    connection, encryption methods, timeouts, and so forth. Correct configuration as necessary and
    customize the environment to suit your needs. For example, if you are using OpenSSH you can
    access the `sshd_config` file.

2.  Use the configuration file to increase the logging level on the server side.

## Troubleshoot Connection Timeout Errors

A generic timeout error, such as `Failed to get operation result within specified timeout`, can be
caused by session limits on the remote SFTP server or by transient network issues.

Check the server-side settings, use the latest version of SFTP Connector, and configure a robust
[reconnection strategy](https://docs.mulesoft.com/mule-runtime/latest/reconnection-strategy-about).

## Troubleshoot Authentication Failures

Log messages that reference `ClientUserAuthService.tryNext` mean that the TCP and SSH handshake
succeeded, but the server rejected the credentials. Verify that the credentials and the
authentication method match what the server expects.

## Interpret Opened and Authed Sessions

In the SSH logs, `Opened` means the SSH handshake is complete, and `Authed` means authentication was
successful. A `Connection reset` or `AuthTimeout` error while the session is `Opened` means that
authentication failed or timed out.

## Troubleshoot Mule Application Issues

Sometimes you are not sure why the application is failing and you require a better understanding of
what is going on in the app’s interaction with the SFTP server.

To resolve this error:

- Use the configuration file to increase the logging level on the server side.

- Try to replicate the issue using an SFTP client, for example, Cyberduck or Filezilla. If the issue
  also occurs with these clients, then it is likely that the issue is not related to the Mule app.

- Get better and more detailed logs on the Mule app side by enabling verbose logging for SFTP
  Connector:

  1.  Access Anypoint Studio and navigate to the **Package Explorer** view.

  2.  Open your application’s project name.

  3.  Open the `src/main/resources` path folder.

  4.  Open the `log4j2.xml` file inside the folder.

  5.  If the following line is already in the `log4j2.xml` file, uncomment it to enable it;
      otherwise, add it:

      ```xml
          <AsyncLogger name="org.mule.extension.sftp" level="DEBUG"/>
      ```

  6.  To ensure the correlation ID is passed to child threads and visible in SSH logs, include the
      following argument in your run configuration:

      \-Dlog4j2.isThreadContextMapInheritable=true

- Try to minimize or remove unnecessary DataWeave data transformations (you could even use hard
  coded data) to minimize app’s complexity and determine whether the issue is with the interaction
  between the app and the SFTP server.

To get further information about enabling verbose logging for SDK components in your Mule
application, see the [Troubleshooting SDK components](https://docs.mulesoft.com/mule-sdk/latest/troubleshooting)
documentation.

## Enable Apache SSHD Library Logging

> [!NOTE] Enabling TRACE level logging for `org.apache.sshd` generates a high volume of debug logs
> that can cause severe performance degradation, including high CPU usage, thread contention, and
> system-wide delays.

1.  Access Anypoint Studio and navigate to the **Package Explorer** view.

2.  Open your application’s project name.

3.  Open the `src/main/resources` path folder.

4.  Open the `log4j2.xml` file inside the folder.

5.  Add this line to enable Apache SSHD library logging:

    ```xml
        <AsyncLogger name="org.apache.sshd" level="TRACE"/>
    ```

## Enable SSL/TLS Handshake Debugging

For diagnosing SSL/TLS handshake issues, add this argument to your run configuration:

`-M-Djavax.net.debug=ssl,handshake`

This argument enables detailed SSL/TLS debugging output. Use the argument only when troubleshooting
encryption-related connection issues.

## Understand Common Throws

Here is a list of common throws messages and how to interpret them.

- SFTP:ILLEGAL\_PATH

  The specified path is invalid because, for example, it does not exist.

- SFTP:FILE\_ALREADY\_EXISTS

  An attempt was made to create a file at the same location and with the same name as an existing
  file. This happens, for example, when attempting to write a file using the CREATE\_NEW write mode
  to the path of an already existing file.

- SFTP:ACCESS\_DENIED

  An operation made an attempt to access an SFTP server path and perform an action for which the
  user has not been granted permission.

- SFTP:FILE\_LOCK

  An operation made an unsuccessful attempt to acquire a lock over a file.

- SFTP:ILLEGAL\_CONTENT

  The \*Write\* operation received invalid content to write.

- SFTP:CONNECTIVITY

  The connection to the SFTP server was interrupted.

- SFTP:INVALID\_CREDENTIALS

  Authentication against the SFTP server failed due to invalid credentials.

- SFTP:CONNECTION\_TIMEOUT

  The attempt to connect to the SFTP server timed out.

- SFTP:CANNOT\_REACH

  An error occurred while attempting to establish the connection to the indicated SFTP server host
  and port. Typically, the connection is refused remotely, for example, if no process is listening
  on the remote address or port.

- SFTP:UNKNOWN\_HOST

  Mule cannot determine the IP address of a host.

- SFTP:DISCONNECTED

  The app made too many failed login attempts to a server. This can result from multiple causes, but
  the most common one is invalid credentials.

- SFTP:KEY\_EXCHANGE\_FAILED

  The app tried to make an SSH connection to the server, but failed in the key exchange step.
  Failure may occur during the negotiation or later steps in the key exchange.

- FILE\_DOESNT\_EXIST

  The file to write was deleted.

## Troubleshoot SFTP Connector Issues with a PPK Identity File

When using the SFTP Connector version 2.0.0 and later with the preferred authentication method set
to `PUBLIC_KEY`, you can face issues if the `Identity` file is PPK. The `Apache Mina library`
doesn’t support the PPK file format, so the application fails.

To resolve this issue:

1.  Convert the PPK `Identity` file to PEM by using `PuTTYgen`.

2.  Update the configuration file to use the PEM file.

    ```xml
        <sftp:config name="SFTP_Config" doc:name="SFTP Config" doc:id="34cf9b32-d3de-4171-b6e9-36dc0b25e7c0">
          <sftp:connection host="${host}" username="${user}" identityFile="${app.home}/${file-pem}" passphrase="${pwd}" port="${port}" workingDir="${root-folder}" preferredAuthenticationMethods="#[['PUBLIC_KEY']]">
          </sftp:connection>
        </sftp:config>
    ```

## Standard Append Mode Overwrites or Fails

When using the `APPEND` write mode, SFTP Connector overwrites the existing file instead of appending
data to it, or the operation fails with a generic error. This behavior occurs when the target SFTP
server is a legacy system that doesn’t support the `SSH_FXF_APPEND` flag. Without this flag, the
server can’t natively process a request to append data to an existing file.

To resolve this issue:

1.  In the **Write** operation configuration, set the **Write Strategy** field to `CUSTOM`.

2.  Set the **Write Mode** field to `CUSTOM_APPEND`.

3.  Adjust the **Buffer Size for Write Strategy** field. When using `CUSTOM_APPEND`, this field
    defines the size of the data chunks sent to the server. For legacy servers with high latency or
    restricted packet sizes, adjusting this value can significantly improve performance and
    stability.

> [!NOTE] The `CUSTOM_APPEND` strategy manually calculates the file offset to ensure data is added
> to the end of the file. Use this strategy only for legacy servers that don’t support the
> `STANDARD` strategy, as it doesn’t support concurrent writes to the same file.

## See Also

- [SFTP Connector Reference](https://docs.mulesoft.com/sftp-connector/latest/sftp-documentation)

- [Salesforce Help](https://help.salesforce.com)

- [Known Issues](https://help.salesforce.com/s/issues)