Troubleshooting SFTP Integration Issues

How to effectively troubleshoot common SFTP integration issues

Jared Ellis avatar
Written by Jared Ellis
Updated over a week ago

What can I learn from this page?

How to effectively troubleshoot common SFTP integration issues

Who is this guide for?

Account Admins, IT

Investigating and Resolving any Data Issues

The first step when investigating SFTP data issues is to check the import summary for your most recent import. This will provide specific information about the erroring data in your report so that you can address these in your HRIS.

To find the Import Summary for your last import, please navigate to this page via Account Admin > Import History and select your most recent SFTP import at the top of the page.

The Import Summary option you click into will display the errors that were included in your last import which will need to be adjusted or the page will prompt you to run a manual upload if this is required.

Sync Blocked Due to Swapped Employee IDs

Your sync might be blocked if Culture Amp suspects that one of your employees may have had their details mixed up with another.

If a combination of an employee's Name, Date of Birth, Email, or Employee ID is changed, the sync will be blocked. This is to prevent an employee from accidentally getting access to another employee's private information, such as performance reviews.

If you've intentionally changed the employee's details, you can complete a manual import to bypass this block.

Handling of Inactive Employees

When removing users from the platform, you have two options: you can mark them as inactive, indicating they are former employees with an end date, or deactivate them, with no specified end date. Both options result in the user being made inactive.

Learn more about the differences between former and deactivated employees here.

Mark Users Inactive as Former Employees:

To make users inactive via SFTP as former employees:

  1. Ensure that there is an End Date column included in your user file

  2. Apply an End Date value next to the employee you are deactivating

  3. Following your update, the Culture Amp platform generally does a file sweep every 10 minutes or so and will process any file that has been picked up and process the updates to the platform.

  4. Once the import is processed, those users will show up under your Settings > Users page under the Former User list.

Mark Users Inactive as Deactivated Employees:

  1. Ensure that your SFTP file has an End Date column

  2. Under the End Date column, ensure that the value for the user you would like to deactivate is blank.

  3. Create an Employee Deactivated column in your SFTP file. Make sure that this column comes before any other custom demographics in your file.

  4. Assign TRUE as the value next to the employee/s you are deactivating.

  5. Make sure FALSE is set for any other employees.

  6. Following your update, the Culture Amp platform generally does a file sweep every 10 minutes or so and will process any file that has been picked up and process the updates to the platform.

  7. Once the import is processed, those users will show up under your Settings > Users page under the Deactivated User list.

Alternatively, you can mark users as inactive by deactivating them individually in the platform. Follow the instructions provided here.

Just make sure that once you manually deactivate these users, they are removed from your any file uploads moving forward.

Note: Any updates to inactive employees, such as a changed End Date or any other update to demographic information, will be applied during the import

Failed Imports

Import Attempt not showing in Culture Amp

The import file may be missing one of our mandatory columns, such as Employee Id or Email, or there could be a data issue, such as a duplicate email address error or similar.

Incorrect Format

The file is not in one of our expected formats (CSV UTF-8 (comma separator) or XLSX) or data may contain unsupported (special) characters.

In general, different CSV format options don't handle special characters the same way, which can sometimes change the data formatting resulting in import failures. You will need to ensure that you are using CSV (UFT-8 encoded) format to ensure special characters are formatted so we can read the information correctly.

In the example above the file has failed due to Illegal quoting. When SFTP file upload fails with an "illegal quoting" error, it usually means that the file contains characters or formatting that are not allowed or recognized by the SFTP server.

Here are a few common scenarios that might result in this error during a SFTP file upload:

  1. Special Characters: The file contains special characters (such as quotation marks, apostrophes, or certain symbols) that are not properly escaped or quoted according to the SFTP server's requirements.

  2. Incorrect Encoding: The file is encoded using a character encoding that is not supported by the SFTP server, leading to errors when the server attempts to parse the file.

  3. Invalid File Format: The file format (e.g., JSON) is not recognized or supported by our SFTP server, causing parsing errors during the upload process.

  4. Mismatched Quotes or Brackets: The file contains mismatched quotation marks, brackets, or other delimiters, which can confuse the SFTP server's parsing mechanism and result in an "illegal quoting" error.

  5. File Corruption: The file may be corrupted or improperly formatted, leading to errors during the upload process.

To resolve this error during SFTP file upload, you may need to:

  • Review the file contents to identify and correct any formatting issues or special characters.

  • Verify that the file format matches the expectations of the SFTP server. E.g. it is in CSV UTF-8 (comma separator) or XLSX format and does not contain unsupported (special) characters.

  • If necessary, regenerate or recreate the file to ensure it is not corrupted or improperly formatted.

Destination Folder

The upload to Culture Amp is to the root directory of our SFTP server, so the destination folder should be left blank. Some SFTP clients / HRIS ask for a value, if so it can be listed as "/".

Multiple Uploads in Quick Succession

Our SFTP integration is designed to process one mass employee file at a time, and between each file, we wait for approx 10 mins before checking if there are further files to process. Although multiple files (with unique file names) can be sent in quick succession, it’s likely to take a while for all of the files to be imported.

Multiple transmissions of the same-named file, within a 10 to 15-minute window, will result in the failure of the second file. The second file would need to have a new name in order for the second transmission to be successful.

SSH Key Pairs

Our SFTP only supports OpenSSH key pairs, not SSH2. If your HRIS or command-line tool generates keys in SSH2 format, you can convert them to openSSH using the instructions in the guide below.

Common Error Messages

"Access denied"

Expected if:

  • You try to put the file in an actual folder, or even the ‘failed’ folder. The upload is to the root directory of our SFTP server, so the destination folder should be left blank. If a value is required, then it can just be listed as “/“.

  • You try to complete any other action besides the PUT (post) request to send the complete file. That includes any MOVE, RENAME, READ, DELETE or GET.

    For example, if you’re sending the file in parts and then renaming it to one complete file. We would not accept the 'RENAME' request and additionally also reject the .filepart file type as this is not accepted by our server.

  • We’ve seen this with the SFTP client called WinSCP that splits the file into two separate files. Adjusting the preferences should allow the file to be sent as 1 complete file, rather than in parts.

  • Time-stamping is another example, which has been noted with WinSCP. The final action as part of a file transfer is sometimes set to add a time-stamp. Again, as we don't support any additional actions, it's likely you may see an error message. In some cases, the file may have been successfully transferred, so the error can be disregarded, but to avoid the error, the recommendation would be to turn off setting permissions or preserving timestamp. Alternatively you could turn on ‘Ignore permission errors’ option.

  • You are trying to send through files with the same name. Ensure that there is a differentiating factor such as adding time stamps to the file name to make each file name different.

"Connection refused"

You may receive a 'connection refused' error when setting up an SFTP client. This could be because your organization has an internal Firewall (either a local or network firewall) that's blocking the SFTP connection.

If this is the case, your firewall needs to be configured to allow outbound access via the hostname (NOT bound to a specific IP address: the IP will change) on TCP Port 22.

Make sure the hostname and username you use to set up your SFTP client are copied directly from the setup form in Culture Amp. Both are case-sensitive.

"Unexpected server shutdown"

Expected if attempting to negotiate a connection with an unsupported SFTP protocol version (0, 1, or 2). We support 4, 5, and 6.

Other / unknown errors

Some SFTP clients have an Event log where you can access a Payload. In the event of an error, this can often help identify the root cause. Example:

Event log:

HTTP Error response code 422 with response state text: Unprocessable Entity; Click text to download payload for further details



Did this answer your question?