Contact Us 1-800-596-4880
  1. Homepage
  2. SFTP Connector (2.4)

  3. Troubleshooting SFTP Connector

All Connectors

Troubleshooting SFTP Connector - Mule 4

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 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 and for the library Apache Mina:

    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:

          <AsyncLogger name=“org.mule.extension.sftp” level=“TRACE”/>
    <AsyncLogger name=“org.apache.sshd” level=“DEBUG”/>

    6. Add the following argument to your run configuration:

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

    7. 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 documentation.

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.

        <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>

See Also

Back to top
View on GitHub