Debug Common Errors in SFTP-Based File Transfer Integrations

Use Case:  This integration debugging script and approach is used to analyze and resolve common runtime errors in SFTP-based file transfer services, especially during file archival (Move File) operations.
It helps identify issues related to missing filenames, incorrect mappings, and payload inconsistencies when transferring files between source and target SFTP servers.

 

Introduction

This blog explains a structured debugging approach for SFTP File Transfer integrations where files are read from a source SFTP server, transferred to a target SFTP server, and then archived.

A common production issue occurs when the integration fails during the archive/move file step with errors like FTP_MOVE_FILE_NOT_FOUND. This usually happens due to incorrect payload mappings, not due to connectivity issues.

Blog walks through:

  1. Error analysis
  2. Payload inspection
  3. Root cause identification
  4. Corrective actions

The Debugging Approach Serves the Following Purposes:

  • Identifies why the FTP Adapter fails during the file move or archive operation
  • Helps analyze runtime payloads passed to the FTP adapter
  • Detects missing or NULL filename mappings inside for-each loops
  • Ensures correct file reference handling across Read, Write, and Move steps
  • Provides a repeatable approach to debug similar SFTP-related issues

Error Message Encountered: FTP_MOVE_FILE_NOT_FOUND.

File /home/users/yrsc.user1/yrsc/yrsc76/filetrfservice/input/null not found in the location.

Please verify whether file is present at the given location.

Payload Passed to the Error Node:

<nstrgmpr:MoveFile

xmlns:xml="http://www.w3.org/XML/1998/namespace"

xmlns:ns26="http://xmlns.oracle.com/ics/cloud/ftp/move/pull"

xmlns:nstrgmpr="http://xmlns.oracle.com/cloud/adapter/ftp/archiveFileInSFTP_REQUEST/types">

<ns26:FileMoveRequest>

<ns26:directory>

/home/users/yrsc.user1/yrsc/yrsc76/filetrfservice/input

</ns26:directory>

<ns26:filename/>

<ns26:targetDirectory>

/home/users/yrsc.user1/yrsc/yrsc76/filetrfservice/archive

</ns26:targetDirectory>

<ns26:targetFilename>

items2.csv_2024-07-17T03:42:36.753Z

</ns26:targetFilename>

</ns26:FileMoveRequest>

</nstrgmpr:MoveFile>

 

Root Cause Analysis:

  • The directory path is valid
  • The <filename/> element is empty
  • The FTP adapter attempts to move a file named null
  • This occurs when the filename is not mapped correctly from the for-each loop
  • As a result, the adapter cannot locate the file and throws an error

 

Corrected Payload Example:

<ns26:FileMoveRequest>

<ns26:directory>

/home/users/yrsc.user1/yrsc/yrsc76/filetrfservice/input

</ns26:directory>

<ns26:filename>

items1.csv

</ns26:filename>

<ns26:targetDirectory>

/home/users/yrsc.user1/yrsc/yrsc76/filetrfservice/archive

</ns26:targetDirectory>

<ns26:targetFilename>

items1.csv_2024-07-17T03:42:36.753Z

</ns26:targetFilename>

</ns26:FileMoveRequest>

 

Components Used:

  • SFTP Server (Source) – To read input files
  • SFTP Server (Target) – To receive processed files
  • FTP Adapter (SFTP Mode) – For file listing, reading, writing, and moving
  • For-Each Loop – To process multiple files dynamically

Summary:

This debugging approach helps quickly identify and fix common SFTP file transfer issues caused by incorrect payload mappings. Most FTP adapter errors are not due to connectivity or permissions, but due to missing or NULL filename references during runtime.

By inspecting payloads, validating loop mappings, and following a structured troubleshooting approach, production issues can be resolved efficiently with minimal downtime.

 

Recent Posts