Common Errors with ftp_nb_continue During File Transfer and How to Debug Them

gitbox 2025-09-16

1. ftp_nb_continue Abnormal Return Value

The return value of ftp_nb_continue can be FTP_FINISHED or FTP_FAILED, indicating whether the transfer is complete. If FTP_FAILED is returned, the transfer has failed. If FTP_FINISHED is returned, the transfer has completed successfully. However, in some cases, you may encounter abnormal return values.

Solution:

First, make sure the FTP connection is valid by checking with functions like ftp_connect and ftp_login.
Verify that the target path and permissions are correct, as missing write permissions or an unavailable target folder may cause issues.
Use ftp_error to get error messages from the FTP server, which helps in troubleshooting.

<span><span><span class="hljs-keyword">if</span></span><span> (</span><span><span class="hljs-variable">$result</span></span><span> == FTP_FAILED) {
    </span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"Transfer failed: "</span></span><span> . </span><span><span class="hljs-title function_ invoke__">ftp_error</span></span><span>(</span><span><span class="hljs-variable">$ftp_connection</span></span><span>);
}
</span></span>

2. Connection Timeout

When using ftp_nb_continue for file transfers, improper timeout settings for the FTP connection may cause timeouts, especially when transferring large files.

Solution:

Use ftp_set_option to set FTP timeout options such as FTP_TIMEOUT to prevent the connection from expiring.

<span><span><span class="hljs-title function_ invoke__">ftp_set_option</span></span><span>(</span><span><span class="hljs-variable">$ftp_connection</span></span><span>, FTP_TIMEOUT_SEC, </span><span><span class="hljs-number">90</span></span><span>); </span><span><span class="hljs-comment">// Set timeout to 90 seconds</span></span><span>
</span></span>

Ensure the network connection between the server and client is stable, and the FTP server is not overloaded causing delays.

3. Server Closing Connection

Sometimes the FTP server may unexpectedly close the connection during a transfer, causing ftp_nb_continue to return a FTP_FAILED error.

Solution:

Check the FTP server configuration to ensure it doesn’t terminate idle connections too quickly.
Implement an automatic reconnection mechanism in your code. If a transfer fails, try reconnecting and resuming the upload or download.

<span><span><span class="hljs-keyword">if</span></span><span> (</span><span><span class="hljs-variable">$result</span></span><span> == FTP_FAILED) {
    </span><span><span class="hljs-title function_ invoke__">ftp_close</span></span><span>(</span><span><span class="hljs-variable">$ftp_connection</span></span><span>);
    </span><span><span class="hljs-variable">$ftp_connection</span></span><span> = </span><span><span class="hljs-title function_ invoke__">ftp_connect</span></span><span>(</span><span><span class="hljs-variable">$ftp_host</span></span><span>);
    </span><span><span class="hljs-title function_ invoke__">ftp_login</span></span><span>(</span><span><span class="hljs-variable">$ftp_connection</span></span><span>, </span><span><span class="hljs-variable">$ftp_user</span></span><span>, </span><span><span class="hljs-variable">$ftp_pass</span></span><span>);
}
</span></span>

4. File Path Errors

Incorrect file paths are another common issue. Ensure the upload path and destination path are correct and free of typos.

Solution:

Use the ftp_chdir function to switch to the target directory to make sure files upload to the correct location.
Before transferring files, use ftp_pwd to check the current directory and confirm the path is correct.

<span><span><span class="hljs-variable">$currentDir</span></span><span> = </span><span><span class="hljs-title function_ invoke__">ftp_pwd</span></span><span>(</span><span><span class="hljs-variable">$ftp_connection</span></span><span>);
</span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"Current directory: "</span></span><span> . </span><span><span class="hljs-variable">$currentDir</span></span><span>;
</span></span>

5. File Permission Issues

If the target folder on the FTP server lacks write permissions, ftp_nb_continue may fail to upload files successfully. This problem often occurs in shared hosting environments.

Solution:

Ensure the target folder has the correct permission settings, typically set to 755 or 777 depending on the situation.
If managing the server via cPanel or similar tools, adjust folder permissions directly through the file manager.

<span><span><span class="hljs-title function_ invoke__">ftp_chmod</span></span><span>(</span><span><span class="hljs-variable">$ftp_connection</span></span><span>, </span><span><span class="hljs-number">0777</span></span><span>, </span><span><span class="hljs-variable">$remote_file</span></span><span>);
</span></span>

6. Data Connection Blocking

ftp_nb_continue is non-blocking, but the data connection (the channel used for file transfers) may get blocked. When using passive mode (PASV), firewalls or other network restrictions may cause data connection failures.

Solution:

Try switching to Active Mode to bypass firewall restrictions, using the ftp_pasv function to toggle passive mode.

<span><span><span class="hljs-title function_ invoke__">ftp_pasv</span></span><span>(</span><span><span class="hljs-variable">$ftp_connection</span></span><span>, </span><span><span class="hljs-literal">false</span></span><span>); </span><span><span class="hljs-comment">// Use Active Mode</span></span><span>
</span></span>

Alternatively, adjust the FTP client’s port configuration to avoid restricted ports.

7. Caching Issues

If cache data is not refreshed promptly during file transfers, uploads or downloads may be incomplete, or file contents may not match.

Solution:

Before transferring files, disable any potential caching, or use ftp_nb_put and ftp_nb_get functions directly to avoid cache interference.

8. PHP Resource Limitations

PHP may terminate file transfer operations due to resource limitations, especially for very large transfers. Common restrictions include maximum execution time and memory limits.

Solution:

Use set_time_limit(0) to remove PHP’s maximum execution time restriction.

<span><span><span class="hljs-title function_ invoke__">set_time_limit</span></span><span>(</span><span><span class="hljs-number">0</span></span><span>);  </span><span><span class="hljs-comment">// Remove max execution time limit</span></span><span>
</span></span>

If memory limitations occur, increase the PHP script’s memory limit using ini_set('memory_limit', '512M').

Common Errors with ftp_nb_continue During File Transfer and How to Debug Them