Historical Sync Issues

Historical Sync rebuilds TrustLens customer profiles from your existing WooCommerce orders, refunds, and disputes. It runs in the background through Action Scheduler in small batches. When it works, it’s transparent — the Dashboard banner shows progress and then disappears. When it doesn’t, the failure modes are all in the queue or the data shape. This page covers diagnosis and fixes.

---

Common Symptoms #

• Sync doesn’t start after clicking Run Historical Sync
• Sync starts but stalls partway through
• Sync completes but customer counts look wrong
• Sync runs but trust scores aren’t being populated

---

Symptom 1: Sync Doesn’t Start #

Verify the Click Registered #

Refresh the Dashboard after clicking Run Historical Sync. You should see:

• The banner change from “Run Historical Sync” to a progress bar
• Or a notification “Sync queued”

If neither happened, the form submission may have failed. Check the browser console for JavaScript errors and try again.

Verify Action Scheduler Picked Up the Job #

Go to WooCommerce → Status → Scheduled Actions. Filter by hook trustlens/historical_sync_batch. You should see at least one Pending action.

If no actions are queued, the click didn’t actually trigger queueing. Likely a JavaScript or AJAX error. Check the browser console.

Verify Action Scheduler Is Running #

Even if jobs are queued, they need to actually run. Look at the same Scheduled Actions list — are any actions completing? If not, WP-Cron is stalled. See Scores Not Updating Step 3 for cron fixes.

---

Symptom 2: Sync Starts but Stalls #

The progress bar updates initially but stops moving for 30+ minutes.

Action Scheduler Queue Health #

1. Check Scheduled Actions list
2. Filter to trustlens/historical_sync_batch
3. Look at the most recent state — are actions completing, or stuck Pending?

Memory Issues #

Stalls often correlate with memory exhaustion mid-batch. Symptoms:

• Recent batches show Failed state with memory errors
• PHP error log shows “Allowed memory size exhausted”

Fix: raise PHP memory limit. Add to wp-config.php:

define('WP_MEMORY_LIMIT', '512M');
define('WP_MAX_MEMORY_LIMIT', '512M');

Database Lock Contention #

On very busy stores, the sync’s writes can contend with normal WooCommerce traffic. Symptoms:

• Sync slows dramatically during peak traffic hours
• Database deadlock errors in logs

Fix: run sync during off-peak hours; lower batch size in Settings → Data → Historical Sync batch size.

HPOS Migration In Progress #

If WooCommerce is mid-HPOS-migration, TrustLens sync may pause until the migration completes. Verify under Tools → Scheduled Actions whether HPOS migration jobs are still running.

---

Symptom 3: Sync Completes but Counts Look Wrong #

The banner disappears, but the customer counts in the Dashboard don’t match your expectations.

Check the Minimum Orders Threshold #

Customers below the minimum-orders threshold (default 3) stay in segment Normal at score 50 — they show up in the customer list but don’t contribute to “scored customers” metrics in the same way.

If most of your store’s customers have only 1–2 orders each, they’ll be pinned at 50 and your segment distribution will be heavily Normal.

Check Order Status Filter #

TrustLens counts orders in the completed status by default. If many of your orders are in processing or other statuses, they don’t count toward the customer’s total_orders.

Verify with a sample: pick a customer, count their completed orders in WooCommerce, compare to total_orders in TrustLens.

Check Date Range #

By default, sync processes all historical orders. Some stores configure a date filter — verify Settings → Data → Historical Sync date range.

---

Symptom 4: Sync Runs but Scores Aren’t Populated #

The sync completes, customer records exist, but trust scores all show 50.

Module Toggles #

If all detection modules are disabled, sync builds the customer records but no signals fire. Verify Settings → Modules — at least Returns and Orders should be on.

Sync Skipped Score Calculation #

The sync writes raw event data first, then calls score calculation. If the calculation step was skipped (interrupted sync, partial completion), the scores aren’t updated.

Fix: bulk recalculate from the Customers list after the sync completes.

---

Symptom 5: Sync Repeatedly Fails on the Same Order #

One specific order causes the sync to fail. The Scheduled Actions log shows the same order ID erroring repeatedly.

Corrupted Order Data #

Some old WooCommerce installations have orders with corrupted or missing data — null line items, malformed shipping addresses, etc. The sync may not handle these gracefully.

Workarounds:

• Inspect the order in WooCommerce; fix or delete if corrupted
• Add the order ID to the sync skip list (Settings → Data → Skip orders)
• Report the issue with the failing order’s structure

HPOS-Specific Issues #

Some HPOS edge cases produce orders that look slightly different from legacy orders. Verify the failing order’s HPOS state — is it fully migrated or partially?

---

Symptom 6: Sync Completes Too Fast #

You have 10,000 orders but the sync completes in 30 seconds. Suspicious.

Possible causes:

• Sync was already partially complete (deduplication skipped processed orders)
• Date filter restricted the range
• Order status filter excluded most orders
• HPOS / legacy table mismatch causing the wrong table to be queried

Verify: spot-check by opening a known order’s customer profile in TrustLens. Are they listed? Are their order count and refund stats correct?

---

Rerunning Sync #

Sync is idempotent — it dedupes by order ID and won’t double-count anything. Safe to rerun multiple times.

1. Settings → Data → Run Historical Sync
2. Confirm

If sync has previously completed for an order and the underlying order hasn’t changed, the rerun is fast — it skips already-processed records.

---

Reset and Resync #

If you suspect sync data is corrupted:

1. Back up the database
2. Settings → Data → Delete all TrustLens data
3. Run Historical Sync again

This rebuilds from scratch. Disruptive but produces a clean slate.

---

Sync Progress Visibility #

While sync is running:

• Dashboard banner shows progress percentage and ETA
• Settings → Data → Sync Status shows detailed batch progress
• Scheduled Actions list shows individual batch jobs

Patience: sync of 100,000+ orders can take hours. Don’t repeatedly click Run — that just queues redundant jobs.