Troubleshooting

Stuck on something? This page has fixes for the most common issues. If you do not find yours here, open the Logs page or the FAQ.

Starting Point

Before diving into specific fixes, try these three things:

  1. Check the log — Download the log from the failed run. The error usually tells you exactly what is wrong.
  2. Check system info — Dashboard → System Information. Make sure everything is green or yellow.
  3. Test with a small file — 10-row test CSV narrows down whether the problem is the data or the plugin.

Installation and Activation

Error: "Plugin could not be activated because it triggered a fatal error"

Cause: PHP version is too low or incompatible plugin.

Fix:

  • Check PHP version: your host's control panel or php -v
  • Plugin needs PHP 8.1+
  • Upgrade via your host or in cPanel

WooCommerce Not Found

Error: "This plugin requires WooCommerce."

Fix: Install and activate WooCommerce first. Then activate this plugin.

Fix:

  • Clear browser cache (Ctrl+F5)
  • Check user role — need manage_woocommerce capability
  • Deactivate and reactivate the plugin
  • Check wp-admin/plugins.php shows the plugin as active

Import Problems

Import Fails Right Away

Symptoms: Red "Failed" banner within seconds.

Causes and fixes:

CauseFix
File could not be readCheck file permissions, file path
Wrong formatPlugin couldn't detect format. Pick explicitly in Step 1
Empty fileOpen the file and check it has data
Invalid CSV (broken quotes)Open in Excel, re-save as CSV UTF-8
Missing required columnCheck required columns for your entity type

Some Rows Failed

Symptoms: Result shows Failed: 23 (or some number).

Fix:

  1. Download the log from the run details page
  2. Search for ERROR lines
  3. Each error has a row number — check your file for that row
  4. Common issues:
    • Invalid data (price is "abc", not a number)
    • Missing required field on that row
    • Duplicate SKU (same SKU on two rows)
    • Invalid date format
  5. Fix the file and re-import (use Update Only mode)

Everything Says "Skipped"

Causes:

ModeWhy
Create OnlyEvery SKU already exists — nothing new to create
Update OnlyNo SKU matches — nothing to update
Create + UpdateEvery row failed validation silently

Fix:

  • Check your match key (Step 3). For products, usually SKU
  • Verify SKUs in file actually exist (or not) in the store
  • Switch to Create + Update to handle both cases

Slow Import

Symptoms: 10,000 products take over an hour.

Causes and fixes:

CauseFix
pcntl not installedInstall php-pcntl — makes imports 10x faster
Local infile disabledEnable LOAD DATA LOCAL INFILE in MySQL
Batch size too smallIncrease in Settings → General
Download Images onTurn off or use Deferred
Slow shared hostingUpgrade to VPS for large stores
Stock hash table hugeClean up: wp wkaie delta cleanup --older-than=30d

Import Stops at 50%

Cause: PHP ran out of memory or time.

Fix:

  • Increase PHP memory: add define('WP_MEMORY_LIMIT', '512M'); to wp-config.php
  • Increase max_execution_time to 0 (unlimited) or 300
  • Lower batch size in Settings
  • Run via WP-CLI instead of browser (no timeouts)

Categories Created at Top Level (No Hierarchy)

Cause: Category separator is wrong.

Fix:

  • Wizard → Step 2 → Click Separators
  • Set Category hierarchy to match your file (default >)
  • Common separators: >, /, |

Images Did Not Download

Causes and fixes:

CauseFix
Images setting offSettings → Images → Download Images = Yes
Image URLs return 404Check URLs work in browser
Image URLs require authPlugin cannot auth. Host images elsewhere first
File permissions/wp-content/uploads/ must be writable (755 or 775)
Disk fullCheck disk space on server
Image too largeIncrease upload_max_filesize in php.ini

Variable Product Has No Variations

Cause: Variation rows could not find their parent.

Fix:

  1. Make sure parent row comes BEFORE variation rows in the file
  2. Parent row's SKU must match the Parent column on variation rows
  3. For "id:123" format, make sure the ID actually exists

Prices Show as 0

Cause: Decimal separator mismatch.

Fix:

  • US format uses . — 29.99
  • European format uses , — 29,99
  • Wizard → Step 2 → Transformation on Price column → Number Format

Duplicate Slug Error

Cause: Two products trying to use the same URL slug.

Fix:

  • Plugin auto-appends -2, -3 to duplicates
  • If that is not happening, check Settings → Advanced → "Auto-resolve duplicate slugs"
  • Manually fix in the CSV by giving each product a unique name

Google Sheets Import

"Access Denied" or "403"

Fix:

  • Open the sheet in Google
  • Click Share
  • Set access to "Anyone with the link can view"
  • OR authorize OAuth2 in Settings → Google APIs

Sheet Loads But Returns Wrong Tab

Cause: You have multiple tabs.

Fix: Wizard → Fill in the Sheet Name field with the exact tab name.

"Auto-sync" Not Working

Causes:

CauseFix
No cron runningSet up server cron to call wp-cron.php
Schedule disabledCheck job status = enabled
Sheet is not publicMake public or use OAuth
No changes between runsDelta import skips unchanged rows

FTP / SFTP

Test Connection Fails

Causes:

CauseFix
Wrong hostVerify with FTP client first
Port blockedTry port 21 for FTP, 22 for SFTP
Passive mode requiredSome servers need Passive — plugin auto-tries both
IP whitelistAsk the FTP server admin to allow your server IP
Wrong credentialsTest with FileZilla first

Test Passes But Import Fails

Cause: File path is wrong.

Fix:

  • Verify the full path — try starting with /
  • Some servers chroot the user, so the path is relative to their home

Amazon S3

403 Forbidden

Fix:

Check IAM permissions. User needs:

  • s3:GetObject for reading
  • s3:ListBucket for listing
  • s3:PutObject for writing (export)

Wrong Region

Cause: Bucket is in a different region than configured.

Fix:

  • AWS Console → S3 → your bucket → Properties → AWS Region
  • Set that region in Settings → Amazon S3 → Default Region

Export Problems

Export is Blank

Cause: Filter returns no records.

Fix:

  • Remove all filters and run again
  • Check that the entity actually has records
  • Preview first to see expected row count

Export Is Very Slow

Fix:

  • Plugin auto-streams for 2000+ rows
  • For huge exports, run via WP-CLI or as a background job
  • Reduce column selection — fewer columns means faster export

Cause: File was auto-cleaned up.

Fix:

  • Rerun the export
  • Increase file retention in Settings → Logs

Scheduled Jobs

Jobs Never Run

Fix:

  1. Check job status = enabled
  2. Check WordPress cron: wp cron event list
  3. Set up server cron to trigger wp-cron:
    */5 * * * * curl -s https://your-site.com/wp-cron.php
  4. Test manually: click Run Now on the job

Jobs Run But Fail

Fix:

  • Open History → click the failed run → see error message
  • Most common: source file missing, credentials expired, database issues

Jobs Run Twice

Cause: Duplicate cron registration.

Fix:

  1. Disable the job
  2. Save
  3. Re-enable the job
  4. Verify only one cron entry: wp cron event list | grep wkaie

Performance

Dashboard Takes Forever to Load

Cause: Huge history table.

Fix:

wp wkaie history cleanup --older-than=30d

Memory Exhausted

Fix:

  • Increase memory_limit in php.ini to 512M or 1G
  • Set WP_MEMORY_LIMIT in wp-config.php:
    define('WP_MEMORY_LIMIT', '512M');

Data Issues

Health Check reportRun Health Check to locate and auto-fix most data issues — 23 checks with pass/fail counts and one-click fixes.

Products Show Wrong Category

Fix: Run Health Check → Rebuild Category Hierarchy.

Stock Shows Wrong

Fix:

  • Health Check → Stock Lookup Tables → Rebuild
  • Or: WooCommerce → Status → Tools → Update Product Lookup Tables

Search Returns No Results

Fix: Health Check → Stale WC Lookup Tables → Fix.

Compatibility

Yoast SEO Fields Not Imported

Fix:

  • Settings → Compatibility → Yoast SEO → Enable
  • Save settings
  • CSV column names must be exact: _yoast_wpseo_title, _yoast_wpseo_metadesc, etc.

ACF Fields Empty After Import

Fix:

  • ACF must be active AND field groups must be registered
  • Use acf_ prefix in CSV column names
  • ACF field group must be assigned to Products

Polylang Language Not Set

Fix:

  • Polylang → Languages → Add at least 2 languages
  • CSV must have polylang_language column with valid language code