Sync fails or stalls

A failing sync is the second-most common support case after licence activation. This page walks through the diagnostic flow we use ourselves when investigating customer reports. Most failures resolve at one of the first three steps.

Step 1 — Identify the failure mode#

There are four distinct failure modes. Identify which one you're seeing, then jump to the matching section.

Step 2 — API error from Nivoda#

If the failed sync row contains a message like "Nivoda API responded with 401 / 403 / 429 / 500", the failure is on the Nivoda side. Map the code:

• 401 Unauthorized — your cached bearer token expired and the refresh failed. Usually because the password changed. Go to NivoSync → Settings → API and re-save the credentials to issue a fresh token. See also Nivoda credentials.
• 403 Forbidden — your Nivoda account does not have Catalogue API access. Email Nivoda support to enable it.
• 429 Too Many Requests — you hit Nivoda's rate limit. The plugin retries with exponential backoff (1s, 2s, 4s). If the sync still fails after all retries, your account quota is genuinely exhausted — wait for the quota window (typically 1 hour) and retry. Reduce sync frequency under NivoSync → Settings → Sync → Schedule if this recurs.
• 500 / 502 / 503 — Nivoda's API is having issues. Check Nivoda status and retry later. The plugin will auto-retry on the next scheduled run.
• "Schema validation failed" — Nivoda returned a payload shape the plugin doesn't recognise. This usually means Nivoda has shipped a breaking API change. Email support@nivosync.com with the failing sync log; we'll ship a compatibility patch.

Step 3 — PHP timeout or out-of-memory#

If the sync runs for minutes and dies, the log will contain one of:

• "Maximum execution time of N seconds exceeded"
• "Allowed memory size of X bytes exhausted"
• "Fatal error: cURL error 28 (Operation timed out)"

Recommended PHP settings for syncing a 50k+ catalogue:

; in php.ini or .user.ini
max_execution_time = 600
memory_limit = 512M
post_max_size = 64M

If you cannot change php.ini (shared hosting), set them per-request in wp-config.php:

// Before the "stop editing" line
@ini_set( 'memory_limit', '512M' );
@set_time_limit( 0 );

Use WP-CLI for large syncs#

Even with generous PHP limits, syncing 100k+ diamonds via the admin UI is slow and fragile. Use WP-CLI from the command line:

wp nivosync sync --full

The CLI command bypasses HTTP/PHP-FPM timeouts entirely. Output streams live so you can see progress. Recommended cadence for large catalogues: run the full sync once via CLI, then let the scheduled hourly incremental sync handle deltas.

Use background processing for medium catalogues#

For 10k–50k diamonds, enable NivoSync → Settings → Sync → Background processing (uses Action Scheduler). The sync splits into 500-diamond batches that each fit inside the PHP execution window.

Step 4 — Stuck lock#

If the sync row shows "In progress" for hours, the lock that prevents concurrent syncs has gotten orphaned — usually because a previous sync died without releasing it (PHP killed by hosting provider, server reboot, etc.).

Two ways to release:

• Admin UI: NivoSync → Sync → Force release lock (button only appears when a stale lock is detected).
• WP-CLI: wp nivosync sync --release-lock.

After releasing, the next scheduled sync (or a manual one) will run normally. If the lock recurs after every sync, something is killing PHP mid-run — see Section 3.

Step 5 — Sync runs but diamond count doesn't change#

This is usually a misconfigured filter, not a sync failure. Check:

• NivoSync → Settings → Sync → Filters — the plugin lets you constrain what gets pulled (e.g. lab-grown only, certain shape allowlist, max price). If these are too restrictive, the sync correctly pulls 0 diamonds matching, then writes 0 to cache.
• Stale diamonds removal — the plugin removes from cache any local diamond whose nivoda_id was not returned by the latest sync. So the net change can be +1000 inserted, -1000 removed = 0 visible difference if the catalogue churned. The sync history shows both insertions and removals separately; look at those numbers, not just the final count.
• Hybrid mode — if you are running in api_first hybrid mode (admin shows it under Settings → Hybrid mode), the cache may stay empty by design — the plugin queries Nivoda live on every page load and only caches diamonds users actually viewed.

Step 6 — Diagnostic checklist for "weird" failures#

If none of the above match, run through this once before emailing support — half the time it points at the cause:

1. Action Scheduler health. Tools → Scheduled Actions in WP admin. If pending actions are stuck or failing, your cron is not running. Configure a real cron job: */5 * * * * curl https://yoursite.com/wp-cron.php > /dev/null 2>&1.
2. Database write check. Verify your DB user has INSERT / UPDATE / DELETE on the wp_ns_* tables — a quick test is running a manual sync and watching the log panel for write errors.
3. Object cache poisoning. If you use Redis or Memcached for wp_options, flush it: wp cache flush. The plugin's API credentials and bearer tokens live in autoloaded options and stale cache can mask credential updates.
4. Plugin conflict shortlist. Disable any plugin that hooks into cron or the HTTP API: WP Cron Manager, WP Rocket (in some modes), security plugins. Retry the sync. If it now works, re-enable plugins one by one to find the culprit.
5. PHP version mismatch. The plugin requires PHP 8.1+. If you're on 8.0 it may install but parts of the sync engine will error silently. Confirm with wp eval 'echo PHP_VERSION;'.

Diagnostic data to include in a support ticket#

If you need to email support@nivosync.com, paste the following — it gets us to root cause in one round:

Plugin version: (from Plugins → Installed Plugins → NivoSync)
WP version: 6.7.x
PHP version: 8.1.x
WC version: 9.x.x (if relevant)
Catalogue size: e.g. 47000 diamonds expected
Sync type that failed: full / incremental / manual / scheduled
Failure mode: API error / timeout / stuck lock / filter mismatch
Last 50 lines of the failing sync detail:
  (copy from NivoSync → Sync → History → click the failed row → expand log)

We typically respond same business day with the fix or the next diagnostic.