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

gitbox 2025-09-16

1. ftp_nb_continue Abnormal Return Values

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

Solution:

First, make sure the FTP connection is working properly by using functions like ftp_connect and ftp_login to verify the connection is successful.
Check if the target path and permissions are correct. The issue might be due to missing write permissions or an unavailable target directory.
Use ftp_error to get the FTP server’s error message, which helps identify the problem.

<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, an improperly set FTP timeout may lead to connection timeouts, especially during large file transfers.

Solution:

Use ftp_set_option to configure the FTP timeout option, such as FTP_TIMEOUT, to avoid premature connection expiration.

<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 confirm the FTP server is not overloaded, causing delays.

3. Server Closing the 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 the idle connection timeout is not set too low.
Implement an automatic reconnection mechanism in your code. If the transfer fails, attempt to reconnect and resume 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. Incorrect File Path

Path errors are another common issue. Make sure the upload and destination paths are correct and free of typos.

Solution:

Use the ftp_chdir function to switch to the target directory, ensuring the file is uploaded to the right 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 issue often occurs in shared hosting environments.

Solution:

Ensure the target folder has the correct permissions, typically set to 755 or 777 (depending on requirements).
If managing the server via cPanel or similar tools, you can 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 (used for file transfers) may still be blocked. When using passive mode (PASV), firewalls or network restrictions may cause the data connection to fail.

Solution:

Try switching to Active Mode to bypass firewall restrictions by using the ftp_pasv function to disable 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>

You can also try modifying the FTP client’s port configuration to avoid restricted ports.

7. Caching Issues

If cache data is not refreshed promptly during transfers, it may result in incomplete uploads/downloads or inconsistent file contents.

Solution:

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

8. PHP Resource Limits

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

Solution:

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

<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 maximum execution time limit</span></span><span>
</span></span>

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