Troubleshooting Guide for WP Ultimate CSV Importer

WP Ultimate CSV Importer is a powerful plugin for importing CSV files, XML, TSV, and Excel files into WordPress. You can also use the plugin to export any WordPress data. However, like any flexible tool, issues may pop up during use. This troubleshooting guide covers most of the problems our users faced and how you can fix them if you run into any issues.

Before getting started, ensure your server meets the following requirements for import and export.

Server Requirements for CSV/XML Import and Export #

PHP Configuration #

• PHP version: 7.4 or higher (8.x recommended).
  
• max_execution_time: 300 or higher (depends on file size and server speed).
  
• memory_limit: At least 512M, 1024M preferred for large imports.
  
• upload_max_filesize: At least 128M or higher to match your largest import file.
  
• post_max_size: Larger than upload_max_filesize, e.g., 256M.
  
• max_input_vars: 5000 or higher (useful if importing custom fields).
  
• allow_url_fopen: On (if importing from external URLs).
  
• mbstring, xml, simplexml, json, libxml extensions: Enabled.

You need to change some settings in the php.ini file and enable some extensions listed above in your hosting server setup.

This detail can also be found inside the plugin Settings >> Security and Performance.

File Upload Issues – All Server-Related Issues and Solutions #

1.1 Server Configuration Limits #

A. upload_max_filesize Limit #

Issue: Upload fails or silently truncates when the file exceeds this limit.

Solution: Increase in php.ini file:

upload_max_filesize = 512M

 Or in .htaccess:

If you are using nginx, then add this

php_value upload_max_filesize 512M

B. post_max_size Limit #

Issue: The Entire post payload (including the file) exceeds the permitted size, and uploads fail.

Solution: Modify in php.ini file

post_max_size = 512M

C. max_execution_time Timeout #

Issue: The Upload process times out during a large file upload.

Solution: Modify in php.ini file

max_execution_time = 300

• Alternatively, to avoid this execution time out error, use the SFTP option or chunked upload if possible.
  

D. memory_limit Exhaustion #

Issue: Server runs out of memory during upload processing, causing fatal errors.

Solution: Change in php.ini file

memory_limit = 512M

E. max_input_time Limit #

Issue: Timeout while processing incoming data, causing incomplete uploads.

Solution: Fix by modifying the below line in your php.ini file

max_input_time = 300

1.2 Server Timeout Errors #

• 504 Gateway Timeout

Reason: Nginx timeout while PHP processes upload.

• 524 (Cloudflare)

Reason: Upload or processing exceeds Cloudflare’s 100s timeout.

• 408 Request Timeout: 

Reason: Upload takes too long, client disconnects.

Solutions To Fix:

• Increase proxy_read_timeout (in Nginx server).
  
• Use direct upload (bypassing Cloudflare for large files).
  
• Use FTP uploads instead of HTTP for very large files.
  

1.3 Permissions and Ownership Issues #

• Upload directory (wp-content/uploads or equivalent) lacks write permission.
  
• Incorrect user ownership (e.g., owned by root instead of www-data).

Solution:

Run the below commands to fix the file permission and ownership problems for the uploads folder.

chmod -R 755 /path/to/uploads

chown -R www-data:www-data /path/to/uploads

• Adjust user/group as per your stack.

1.4 Disk Space Exhaustion #

Reason: Uploads fail due to insufficient server disk space.

Solution:

• Monitor with df -h.
  
• Clear unused logs, caches.
  
• Expand storage if consistently hitting limits.

1.5 ModSecurity or Firewall Blocking #

Reason: Security modules block uploads due to:

• Large POST requests.
  
• File types flagged as unsafe.

Solution:

• Review server/firewall logs.
  
• Whitelist your IP or temporarily disable strict rules during upload.
  
• Adjust ModSecurity rules to allow large file uploads safely.
  

WP Ultimate CSV Importer Pro

Get Ultimate CSV/XML Importer to import data on WordPress faster, quicker and safer.

Grab it Now $199/-

1.6 Server Resource Limits (CPU/IO) #

Reason: Shared hosting throttling CPU or IO during large uploads, causing slow uploads and random failures.

Solution:

• Monitor with top or iotop.
  
• Schedule uploads during low-traffic hours.
  
• Upgrade to a higher-tier hosting plan or VPS.
  

1.7 Session and Garbage Collection Issues #

Reason: Long uploads may drop session if session.gc_maxlifetime is too low.

Solution:

session.gc_maxlifetime = 86400

Increase the value in php.ini file or implement keep-alive pings during upload.

1.8 Upload Stuck at 100% #

Issue Reason: Often caused by

• PHP processing file after upload but hitting limits.
• Server expecting a certain content length that mismatches due to corruption.

Solution:

• Validate upload settings.
• Check browser console for JS upload handler errors.
• Review error_log for backend issues during post-upload processing.

Encoding & File Validation Issues in CSV/XML/XLS/XLSX: Issue Reasons and Solutions #

Common Encoding Issues & Reasons #

Below are some common reasons where the encoding issues may arise in multiple file types used for import with WP Ultimate CSV Importer.

• Mojibake (garbled characters)
  Arise due to opening the UTF-8 files in editors expecting a different encoding (e.g., ANSI, ISO-8859-1).
  
• BOM (Byte Order Mark) issues
  UTF-8 BOM may cause issues in some parsers.
  
• Special characters (€, ©, é, etc.) displayed incorrectly
  The file is not saved or read with matching encoding.
  
• CSV delimiter issues
  Characters like , or ; inside fields causing splitting problems when encoding is not handled correctly.
  
• Encoding mismatch on import
  Importing UTF-8 files into Excel defaults to ANSI, leading to corrupted characters.
  
• Hidden control characters (non-printable)
  This can break import parsers or produce unexpected output.
  
• XML Parsing errors due to incorrect declaration
  For example, file content is UTF-8, but the XML header shows encoding=”ISO-8859-1″.
  
• XLS/XLSX content corruption
  This is rare, but can occur if underlying XML inside XLSX is manually modified with wrong encoding.

Recommended Solutions for Encoding Issues: #

• Always save/export files as UTF-8 without BOM unless the importer explicitly requires BOM.
  
• Confirm encoding using tools like:
  
  • file command on Linux (file -bi filename.csv).
    
  • Notepad++ (Encoding menu).
    
  • VS Code (bottom-right encoding indicator).
    
• For Excel CSV issues, use:
  
  • UTF-8 CSV with BOM for compatibility with older Excel versions.
    
  • Alternatively, import via “Data → From Text” specifying UTF-8 manually.
    
• For XML, ensure:
  
  • XML declaration matches the actual encoding.
    
  • Example: <?xml version=”1.0″ encoding=”UTF-8″?>.
    
• Remove hidden control characters using:
  
  • iconv -c -f UTF-8 -t UTF-8 input.csv -o cleaned.csv
    
  • Text editors supporting regex replace for \x00-\x1F.
    

Common CSV File Validation Issues #

The CSV file format is more prone to validation issues and below are the most common reasons:

• Missing or extra columns due to delimiter mismatch.
  
• Unescaped special characters (commas, quotes) inside text fields.
  
• Incorrect newline handling inside quoted fields.
  
• Inconsistent use of quotes.
  
• Empty rows or malformed lines.
  
• Wrong data types (e.g., date formats).
  
• Large file size issues causing truncation during upload.
  

Recommended Solutions for File validation issues #

1. If it’s CSV File Validation:

• Use CSV validation tools (like CSV Lint, or CSVKit).
  
• Confirm that:
  
  • Delimiters and quote characters are consistent.
    
  • All rows have the same number of columns.
    
• Escape fields with special characters using quotes.
  
• Standardize newline characters to LF (\n).
  
• For large files:
  
  • Split into smaller chunks before processing.
    
  • Increase PHP memory limits if used in PHP imports.
    

2. If it’s XLS/XLSX File Validation:

• Prefer XLSX over XLS due to better Unicode handling.
  
• Avoid editing internal XML files unless necessary, and if so, use UTF-8 consistently.

Common Import Issues & Solutions #

1. Import File Not Uploading #

Whenever you encounter an import file not uploading issue with no error message shown, then there could be two possible reasons.

• File Size Too Large: The import file might exceed the server’s maximum upload size.
• Timeout Issues: The server may timeout during the file upload process.

Solutions:

• Increase Maximum Upload Size:
  • Edit or modify the php.ini file and increase the values for upload_max_filesize, post_max_size, and max_execution_time.
  • Alternatively, contact your hosting provider to increase these limits.
• Use FTP for Larger Files: If the file is too large, consider uploading it directly via FTP and using the importer’s FTP option for importing.

2. Import Not Starting or Freezing #

Possible Causes:

• Server Configuration: Your server may have limitations on the execution time or memory allocation.
• CSV File Issues: There could be formatting issues in the CSV file, such as empty rows, special characters, or unexpected line breaks.

Solutions:

• Increase PHP Limits:
  • Modify max_execution_time and memory_limit in php.ini to allow more resources for the import process.
  • Ensure max_input_vars is set to a higher value, such as 5000 or more if you have many fields.

• Check CSV Formatting:
  • Open the CSV file in a text editor to ensure there are no unexpected empty lines, commas, or special characters that may cause issues.
  • Verify and ensure that your CSV file is encoded in UTF-8 format.
• Run Smaller Imports: If your CSV file is large, break it into smaller files and try importing them one at a time.

3. Data Not Displaying After Import #

If you experience that the data appears to be successfully imported, but it’s not visible on the front-end of the website, then there could be some possible causes below.

Possible Causes:

• Field Mapping Issues: The fields in your CSV file may not be properly mapped to WordPress fields.
• Caching Issues: Sometimes, caching plugins may prevent the newly imported data from showing up.

Solutions:

• Review Field Mapping:
  • Ensure that the fields in your CSV file are correctly mapped to their respective WordPress fields. Double-check that custom fields or taxonomies are properly configured.
• Clear Cache:
  • Clear any caching from your caching plugin or browser cache to ensure you’re viewing the latest content.

4. Incorrect Data Formatting After Import #

Possible Causes:

• CSV File Encoding: The encoding of the CSV file might be incorrect, leading to formatting issues.
• Incorrect Date or Number Formatting: The regional settings of your WordPress site may not match the format used in the CSV file.

Solutions:

• Ensure Correct Encoding:
  • Ensure that you have saved your CSV file with UTF-8 encoding. If unsure, you can use a text editor like Notepad++ to verify and adjust the encoding.
• Check Date & Number Formats:
  • Ensure the date format in your CSV file matches the format used in your WordPress site’s settings. Go to Settings > General in the WordPress admin to review and update the date and time format.

5. Missing Images or Attachments #

The images or attachments linked in the CSV file are not imported correctly.

Possible Causes:

• Incorrect Image URLs: The image URLs in your CSV file might be broken or incorrectly formatted.
• Server Restrictions: Your server might not allow external URLs to be downloaded.

Solutions:

• Check Image URLs:
  • The image URLs in your CSV file should be accurate and publicly accessible
• Use Local Paths:
  • For better results, try using the local path for images rather than external URLs.
• Increase Server Permissions:
  • Ensure that the server allows external requests and that the necessary permissions are set to download files during the import.

6. Plugin Conflicts #

The plugin is behaving unexpectedly, such as not importing data, or showing errors in the import process.

Possible Causes:

• Conflicts with Other Plugins: Another plugin on your WordPress site may be interfering with the import process.

Solutions:

• Deactivate Other Plugins:
  • Deactivate other plugins one by one to identify which one is causing the conflict. You can also try deactivating all non-essential plugins temporarily to isolate the issue.
• Check for Theme Conflicts:
  • Sometimes, the active theme might interfere with the import. So, you can Switch or change your theme to the default WordPress theme and check if the issue still persists.

7. Plugin is Not Showing in Admin Panel #

The WP Ultimate CSV Importer plugin does not appear in the WordPress admin menu.

Possible Causes:

• Plugin Installation Issues: The plugin might not have been installed or activated correctly.
• Permission Issues: Lack of permission on your user account to access the plugin.

Solutions:

• Reinstall the Plugin:
  • Try reinstalling the plugin by deleting it from the WordPress admin panel and re-uploading it. Ensure that it is activated once installed.
• Check User Permissions:
  • Ensure your WordPress user role has the necessary permissions to access the plugin and its features. Administrator access is required for full functionality.

8. Unexpected Import Results (Extra Data, Wrong Rows) #

The import shows extra rows, empty fields, or incorrect data that doesn’t match the source CSV file.

Possible Causes:

• Duplicate Rows in CSV: There may be extra empty rows or duplicate data in your CSV file.
• Improper Field Mapping: Incorrect field mapping could cause data to be placed in the wrong columns or fields.

Solutions:

• Review CSV for Duplicates:
  • Open your CSV file in a spreadsheet editor (such as Excel or Google Sheets) and remove any blank rows or duplicated rows.
• Check Field Mapping:
  • Double-check the mapping of each CSV field to its corresponding WordPress field during the import process. Incorrect mappings could cause data to populate incorrectly.

Handling Import/Export Termination Issues #

If your import or export process stops suddenly before the entire process is completed, it means your server has terminated the process due to time, memory, or resource limits.

Here’s What You Should Do First:

2.1 Lower Records Per Iteration #

Go to: Import configuration(during import) and choose the intuitive file processing option provided with text like “Do you want adaptive file processing of record?”

• Start by reducing the record number processed per batch.
  
• Try:
  
  • 50 → 20 → 10 → 1
    
• This reduces the workload per request, helping to avoid server timeouts or memory exhaustion.
  

2.2 If it still Fails with 1 Record Per Iteration then check the below – Common Import and Export Server Errors #

A. 500 – Internal Server Error #

• General server error occurs during import/export. It is often occurred due to following reasons:
  
  • PHP fatal errors in a plugin/theme.
    
  • Insufficient memory (memory_limit).
    
  • Corrupt .htaccess.
    
  • PHP misconfigurations.
    

Here’s how to fix it:
Check error_log to identify the specific PHP error.
Increase memory_limit, for example, 512M.
Disable conflicting plugins/themes and retry the import/export.
Regenerate .htaccess (via Settings > Permalinks > Save).
If using WP CLI or cron, verify the correct PHP path.

B. 503 – Service Unavailable #

• Server is overloaded or undergoing maintenance.
  
• Can occur if:
  
  • Import/export processes exceed available CPU or memory.
    
  • Hosting provider rate-limits resource-heavy processes.
    
  • Server security systems (ModSecurity, WAF) block the import/export script.
    

How to fix them:
Wait and retry during off-peak times.
Use batch processing (smaller record chunks per import, in other words, iteration import/export).
Whitelist your server’s IP in security systems.
Check with hosting to increase resource limits or review server logs.

C. 504 – Gateway Timeout #

• The server did not respond within the gateway/proxy’s timeout period.
  
• Common during large imports/exports or on shared hosting.
  

How to fix them:
Increase max_execution_time and max_input_time.
Use cron-based imports/exports to bypass browser timeouts.
Split large files into smaller chunks.
Check server load and optimize resource usage during import/export.

D. 524 – A Timeout Occurred (Cloudflare) #

• Cloudflare reached your server but the server did not respond within 100 seconds.
  

How to fix them:
Use WP-CLI or cron jobs to run large imports/exports.
Temporarily pause Cloudflare proxy for your domain while processing.
Optimize import/export to run in smaller batches.
Consult hosting to review server processing delays.

E. 502 – Bad Gateway #

• Upstream server did not respond properly.
  
• Can occur if:
  
  • PHP-FPM crashes during heavy import/export.
    
  • Reverse proxy (Nginx) configuration issues.
    

How to fix them:
Check PHP-FPM and Nginx logs.
Restart PHP-FPM or web server.
Optimize import/export to avoid overwhelming the server.

F. 403 – Forbidden #

• Permissions or security restrictions blocking import/export operations.
  

How to fix them:
Check folder permissions (like 755 or 775).
Review .htaccess or server security rules blocking file processing.
Whitelist IP or adjust ModSecurity/WAF rules.
Verify user roles/capabilities if import/export is triggered via plugins.

G. 404 – Not Found #

• Import/export endpoint or file URL not accessible.
  

How to fix them:
Verify correct file paths and URLs.
Check permalink settings and regenerate .htaccess.
Ensure files exist and are readable on the server.

H. 408 – Request Timeout #

• The client took too long to send a request.
  

How to fix them:
Check network conditions during file upload.
For large files, try FTP/SFTP upload instead of other upload.
Increase max_input_time in php.ini.

WP Ultimate CSV Importer Pro

Get Ultimate CSV/XML Importer to import data on WordPress faster, quicker and safer.

Grab it Now $199/-

Best Practices #

• Use a Staging Environment

Always test your imports in a staging site before running them on your live (production) site.

• Try Our Trial Instances

Sign up for a private trial here if you want to test all your use cases before purchasing. If you run into any issues while trying on a trial instance, please feel free to reach out to our support team for any help.

• Contact Our Team for Any Support

If you encounter any issues while importing or exporting or need any guidance to try specific use cases, reach out to our support team at [email protected] with the import/export file sample, exact error message screenshot, and details about when they appear, details about php version and server settings, and share relevant logs like error_logs, or PHP-FPM logs. Our team is ready to help troubleshoot any issues and answer your questions.