Skip to content

Troubleshooting

Common Issues

Section titled “Common Issues”

Connection Issues

Section titled “Connection Issues”

Can’t connect to BigCommerce

Section titled “Can’t connect to BigCommerce”

Symptoms:

  • Red “Connection failed” indicator in Settings > General
  • “Invalid credentials” error message
  • “Test Connection” button shows error

Solutions:

  1. Check connection status:

    • Go to Commerce Connect → Connect
    • Look for Connection Status indicator
    • Status should show store name if connected

  2. Reconnect if needed:

    • If connection failed, you may need to go through the signup flow again
    • Navigate to Commerce Connect → Connect
    • Click Continue to restart the connection process

Diagnostic: If Connect tab shows your store name, connection is working.

Sync Issues

Section titled “Sync Issues”

Products not syncing

Section titled “Products not syncing”

Symptoms:

  • Product count shows 0 in Settings > Products
  • “Last sync” timestamp doesn’t update
  • Sync completes but no products appear

Solutions:

  1. Check sync status:

    • Go to Settings > Commerce Connect > Products
    • Look at Sync Status panel
    • Check Product Count display
    • Review Last Sync timestamp

  2. Trigger manual sync:

    • Click Sync Now button in Settings > Products
    • Watch progress indicator
    • Wait for “Sync complete” message

  3. Verify products exist in BigCommerce:

    • Log into BigCommerce admin
    • Go to Products page
    • Ensure products are Published (not draft/hidden)
    • Check product visibility settings

  4. Check product count after sync:

    • Go to Settings > Commerce Connect > Data
    • View Product Statistics
    • If count is still 0, check BigCommerce product visibility

Diagnostic: If product count matches BigCommerce, sync is working correctly.

Sync is very slow

Section titled “Sync is very slow”

Symptoms:

  • Sync progress bar moves very slowly
  • Sync can take hours for large catalogs (1000+ products)
  • Timeout errors in sync status

Solutions:

  1. Adjust batch size:

    • Go to Settings > Commerce Connect > Advanced
    • Find Batch Size setting
    • Reduce from 50 to 25 products per batch
    • Save and retry sync

  2. Check sync progress in real-time:

    • Watch Sync Status panel during sync
    • Note “X of Y products synced” counter
    • If progress stops, check error messages below

  3. Contact hosting support:

    • If sync consistently times out
    • May need PHP memory limit increase
    • May need max execution time adjustment

Diagnostic: Successful sync should show “100% complete” with product count matching BigCommerce.

Display Issues

Section titled “Display Issues”

Blocks not showing products

Section titled “Blocks not showing products”

Symptoms:

  • Product grid block is empty
  • “No products found” message
  • Block shows placeholder but no products

Solutions:

  1. Verify products are synced:

    • Go to Settings > Commerce Connect > Products
    • Check Product Count — should be > 0
    • If 0, run sync first (see “Products not syncing” above)

  2. Check block filter settings:

    • Edit the page with the product block
    • Click on the product grid block
    • Review Block Settings sidebar:
      • Category filter: Is it excluding all products?
      • Search query: Is it too restrictive?
      • Product status: Set to “Published” only?
    • Adjust filters and save

  3. Clear WordPress® caches:

    • Go to Settings > Commerce Connect > Data
    • Click Clear Cache button
    • Refresh the front-end page

Diagnostic: If product count shows 50+ but block is empty, check block filters first.

Images not loading

Section titled “Images not loading”

Symptoms:

  • Broken image icons (🖼️ with red X)
  • Alt text shows but no image
  • Placeholder images instead of product photos

Solutions:

  1. Re-sync product images:

    • Go to Settings > Commerce Connect > Products
    • Click Sync Now button
    • Wait for completion
    • Refresh front-end page

  2. Check image URLs:

    • Edit product in WordPress® admin
    • Scroll to Product Gallery
    • Click image to verify URL loads in new tab
    • If 404, image may have been deleted in BigCommerce

  3. Verify BigCommerce image settings:

    • Log into BigCommerce admin
    • Edit product with missing image
    • Check Images tab has uploaded images
    • Ensure images are not set to “hidden”

Diagnostic: If images load in BigCommerce admin but not WordPress®, re-sync products.

Performance Issues

Section titled “Performance Issues”

Slow page loads

Section titled “Slow page loads”

Symptoms:

  • Product pages take 5+ seconds to load
  • High Time to First Byte (TTFB)
  • Browser “waiting for server” indicator

Solutions:

  1. Enable caching:

    • Go to Settings > Commerce Connect > Performance
    • Enable Cache Product Data
    • Set Cache Duration to 3600 seconds (1 hour)
    • Save changes

  2. Enable lazy loading:

    • Go to Settings > Commerce Connect > Performance
    • Enable Lazy Load Product Images
    • Save and test front-end page speed

  3. Check database health:

    • Go to Settings > Commerce Connect > Data
    • View Database Statistics
    • If product count is very high (10,000+), contact support

Diagnostic: After enabling cache, page loads should drop under 2 seconds.

Webhook Issues

Section titled “Webhook Issues”

Real-time sync not working

Section titled “Real-time sync not working”

Symptoms:

  • Products updated in BigCommerce don’t sync immediately
  • Manual sync works but automatic doesn’t
  • “Webhook Status” shows inactive

Solutions:

  1. Check webhook status:

    • Go to Settings > Commerce Connect > Data
    • Look for Webhook Status indicator
    • Should show “Active” with green checkmark

  2. Re-register webhooks:

    • Go to Settings > Commerce Connect > Data
    • Click Re-register Webhooks button
    • Wait for “Webhooks registered successfully” message

  3. Verify in BigCommerce:

    • Log into BigCommerce admin
    • Go to Settings > Webhooks
    • Look for webhooks with your WordPress® URL
    • Status should be “Active”
    • Check Delivery Logs for errors

  4. Test webhook manually:

    • In BigCommerce, edit any product
    • Change product title
    • Save product
    • Check if change appears in WordPress® within 30 seconds

Diagnostic: If webhook status is green and test update syncs within 30 seconds, webhooks are working.

Error Messages

Section titled “Error Messages”

”Delta sync collision detected”

Section titled “”Delta sync collision detected””

Meaning: Product was changed in both BigCommerce and WordPress® at the same time.

Solution:

  1. Decide which version to keep (usually BigCommerce is source of truth)
  2. Go to Settings > Commerce Connect > Products
  3. Click Force Full Sync button
  4. This will overwrite WordPress® data with BigCommerce data

”Insufficient memory”

Section titled “”Insufficient memory””

Meaning: WordPress® ran out of PHP memory during sync.

Solution:

  1. Go to Settings > Commerce Connect > Advanced
  2. Reduce Batch Size to 10-25 products
  3. Try sync again
  4. If still failing, contact WP Engine support to increase PHP memory limit

”API rate limit exceeded”

Section titled “”API rate limit exceeded””

Meaning: Too many API requests to BigCommerce in short time.

Solution:

  1. Wait 1 hour — BigCommerce rate limits reset hourly
  2. Go to Settings > Commerce Connect > Advanced
  3. Reduce Sync Frequency from “Every 15 minutes” to “Every hour”
  4. Reduce Batch Size to 25 products
  5. Save and retry sync

Debug Mode

Section titled “Debug Mode”

Enable debug mode for detailed error logging:

  1. Go to Settings > Commerce Connect > Advanced
  2. Enable Debug Mode
  3. Save changes
  4. Reproduce the issue
  5. Go to Settings > Commerce Connect > Data
  6. Click View Debug Log button
  7. Copy log contents to share with support

Important: Disable debug mode when done — it can slow down your site.

Status Indicators Quick Reference

Section titled “Status Indicators Quick Reference”

Connection Status (Settings > General)

Section titled “Connection Status (Settings > General)”
  • ✅ Green checkmark: Connected successfully
  • ❌ Red X: Connection failed — check credentials
  • ⚠️ Yellow warning: Partial connection — check API scopes

Sync Status (Settings > Products)

Section titled “Sync Status (Settings > Products)”
  • ✅ “Last sync: 2 minutes ago” — Syncing regularly
  • ❌ “Last sync: Never” — Run initial sync
  • ⚠️ “Sync in progress” — Wait for completion

Webhook Status (Settings > Data)

Section titled “Webhook Status (Settings > Data)”
  • ✅ “Active” — Real-time sync working
  • ❌ “Inactive” — Re-register webhooks
  • ⚠️ “Partially active” — Some webhooks missing

Getting Help

Section titled “Getting Help”

Before contacting support

Section titled “Before contacting support”

  1. Check connection status:

    • Settings > General > Connection Status
    • Must show green checkmark

  2. Check product count:

    • Settings > Products > Product Count
    • Should match BigCommerce product count

  3. Enable debug mode and reproduce issue:

    • Settings > Advanced > Enable Debug Mode
    • Reproduce the problem
    • Settings > Data > View Debug Log

Contact Support

Section titled “Contact Support”

Include this information:

  • WordPress® version
  • PHP version
  • Commerce Connect version
  • Screenshots of Settings panels showing the issue
  • Error messages (full text)
  • Debug log excerpt (if enabled)
  • Steps to reproduce

For Developers

Section titled “For Developers”

Advanced troubleshooting and diagnostics are available via WP-CLI commands.

See CLI Commands for:

  • Database diagnostics
  • Webhook testing
  • Advanced sync options
  • Performance profiling
  • System information export