Sync issues

The dashboard shows a short message with a link to the matching section below when a sync fails or a store needs attention. Each section has a stable anchor (for example #feed_unreachable), so links always land on the right answer.

Under Catalog → Sync you can see every run, its counts and its error. Sync now starts a new run.

Sync errors

The store credentials were rejected

Code: auth_failed
Cause: The platform revoked or expired ShopAssist's access, for example after the app was reinstalled or the integration deleted.
Fix: Reconnect the store from Settings → Connection.

The plugin rejected our signature

Code: signature_invalid
Cause: The plugin could not verify ShopAssist's signed requests, usually after a key rotation or a clock problem.
Fix: Check the server clock; if it persists, reconnect the store.

A permission is missing

Code: scope_missing
Cause: A capability needs a Shopify scope or Magento ACL resource that is not granted.
Fix: Grant the permission in the embedded app, or reconnect.

The platform limited our requests

Code: rate_limited
Cause: The platform answered with rate limiting. The sync retries automatically.
Fix: No action needed unless it repeats for hours.

The platform returned an error

Code: platform_error
Cause: The store answered with a server error.
Fix: Check your store's error logs; the sync retries.

The platform took too long

Code: timeout
Cause: A request to your store timed out.
Fix: Check server load and timeouts for the ShopAssist routes.

Your store could not be reached

Code: store_unreachable
Cause: DNS, TLS, a firewall, basic authentication or maintenance mode stopped our requests. As a sync error it fails one run; as a health warning it means every call failed for more than an hour.
Fix: Check your hosting and firewall, then see the connection troubleshooting for the specific reason.

The store sent an invalid response

Code: invalid_response
Cause: The plugin or RPC endpoint returned data that does not match the protocol.
Fix: Update the plugin, or check your Generic RPC implementation.

The plugin is too old

Code: plugin_outdated
Cause: The plugin's protocol is below the supported minimum or a route is missing. Syncs fail and the store shows a health warning until you update.
Fix: Update the ShopAssist plugin.

The product feed could not be read

Code: feed_invalid
Cause: The feed returned an HTTP error, was too large, could not be parsed, was empty or shrank suspiciously.
Fix: Open the feed URL, fix its format and check the feed's last error in Catalog → Sync.

The product feed could not be downloaded

Code: feed_unreachable
Cause: The feed URL did not answer or needs credentials.
Fix: Check the URL and credentials of the feed.

A batch was too large

Code: payload_too_large
Cause: A push or plugin batch exceeded the size limit.
Fix: Send smaller batches (see the Catalog Push API limits).

Health warnings

A firewall blocks ShopAssist

Code: waf_blocked
Cause: A challenge page was returned for our requests.
Fix: Allow the egress IPs listed on /docs/security/egress-ips.

Store in maintenance mode

Code: maintenance_mode
Cause: The store answers our requests with its maintenance page.
Fix: Update the module or allow our IP addresses.

Copy of another site detected

Code: clone_detected
Cause: The site identity changed, typically on a staging copy.
Fix: Reconnect on the real site, or remove the connection on the copy.

Repeated invalid plugin responses

Code: plugin_response_invalid
Cause: Three or more invalid responses within an hour.
Fix: Update the plugin or contact support.

No heartbeat from the plugin

Code: heartbeat_missing
Cause: The plugin has not reported in (over 2 hours; PrestaShop 26 hours).
Fix: Check that cron runs and the plugin is active.

Magento cron is not running

Code: cron_not_running
Cause: The cron lag is over 15 minutes.
Fix: Fix the Magento cron configuration.

Indexer not on schedule

Code: indexer_not_scheduled
Cause: The shopassist_products indexer is not set to Update by Schedule.
Fix: Set the indexer mode to Update by Schedule.

Action Scheduler is lagging

Code: action_scheduler_lagging
Cause: WooCommerce background jobs are more than 30 minutes behind.
Fix: Add a system cron for WP-Cron.

WP-Cron is disabled

Code: wp_cron_disabled
Cause: WP-Cron is off and no system cron runs.
Fix: Add a system cron job.

Change backlog in the plugin

Code: outbox_backlog
Cause: More than 5,000 pending changes or the oldest is over an hour old.
Fix: Check connectivity between your store and ShopAssist.

Changes that could not be delivered

Code: outbox_dead_rows
Cause: Some changes failed permanently.
Fix: Check connectivity and contact support if they remain.

Sync is behind

Code: sync_lagging
Cause: No successful incremental sync for three intervals.
Fix: Open Catalog → Sync for the last error.

Plan product limit reached

Code: catalog_limit_reached
Cause: The plan's products_per_store limit is reached; only the first products are searchable.
Fix: Upgrade the plan or hide products from the assistant.

Only part of the catalog is searchable

Code: plan_product_limit
Cause: Alias of catalog_limit_reached shown in the catalog screen.
Fix: Upgrade the plan or hide products from the assistant.

The catalog shrank suspiciously

Code: catalog_shrink_suspected
Cause: A sync would delete an unusually large share of products, so the shrink guard stopped it.
Fix: Check the source; confirm the sync if the shrink is intended.

A cart reference is invalid

Code: cart_ref_invalid
Cause: A variant's cart reference failed validation, so add-to-cart cannot work for it.
Fix: Update the plugin or the feed data.

Unknown stock location

Code: location_stub_created
Cause: Stock arrived for a location code ShopAssist did not know; a stub was created.
Fix: Complete the location's details in the dashboard.

Feed failing

Code: feed_failing
Cause: Three consecutive feed fetches failed.
Fix: Fix the feed URL or credentials.

Generic RPC failing

Code: generic_rpc_failing
Cause: Three consecutive RPC health checks failed.
Fix: Fix the RPC endpoint.

B2B pricing detected

Code: b2b_pricing_detected
Cause: Customer-group or shared-catalog prices were detected.
Fix: Consider switching off price statements in Guardrails.

Prices hidden for guests

Code: hide_prices_plugin
Cause: A plugin hides prices from guests.
Fix: Consider switching off price statements in Guardrails.

Multi-currency plugin active

Code: multi_currency_plugin
Cause: The assistant states prices in the store's base currency.
Fix: No action needed; tell shoppers in your persona if useful.

Two back-in-stock systems

Code: native_back_in_stock_active
Cause: WooCommerce's own stock notifications are enabled as well.
Fix: Choose one system.

Store in coming-soon mode

Code: coming_soon
Cause: WooCommerce coming-soon mode is on.
Fix: Switch it off when you launch.

Merchandise returns are off

Code: order_returns_disabled
Cause: PrestaShop merchandise returns are disabled while ShopAssist returns are enabled.
Fix: Enable merchandise returns or use request mode.

Friendly URLs are off

Code: friendly_urls_off
Cause: PrestaShop URL rewriting is disabled.
Fix: Enable friendly URLs.

Shopify API version fallback

Code: api_version_fallback
Cause: Shopify served another API version than requested.
Fix: None; COEC is alerted.

Identity key rotation pending

Code: identity_rotation_pending
Cause: A new identity secret could not be pushed to the plugin.
Fix: Reconnect the store.

Signed-in customers fail

Code: identity_misconfigured
Cause: Many identity tokens fail verification.
Fix: Check the identity setup for your platform.

Server clock is off

Code: clock_skew
Cause: The plugin's clock is more than 60 seconds off.
Fix: Enable time synchronisation (NTP) on your server.

Connector key rotation pending

Code: connector_rotation_pending
Cause: Rotating the connector secret failed.
Fix: Reconnect the store.

PHP version is end of life

Code: php_eol
Cause: Your PHP version no longer receives security fixes.
Fix: Upgrade PHP.

Platform version is end of life

Code: platform_version_eol
Cause: Your platform version is past its support window.
Fix: Upgrade the platform.

Debug logging is on

Code: debug_log_enabled
Cause: The plugin's debug log is enabled.
Fix: Switch it off in production.

Page cache interferes

Code: page_cache_bypass_needed
Cause: A page cache serves pages that should bypass it.
Fix: Exclude the ShopAssist routes from the page cache.

REST route blocked

Code: rest_route_blocked
Cause: The plugin's REST route is blocked.
Fix: Allow the ShopAssist route.

Change pings are delayed

Code: post_response_ping_unavailable
Cause: The server has no finish-request function, so change pings run slower.
Fix: Use PHP-FPM, or accept the 5-minute poll.

Plugin version unsupported

Code: plugin_unsupported
Cause: The plugin version is below the supported minimum.
Fix: Update the plugin.

Compliance warnings

Accept the data processing agreement

Code: legal_acceptance_required
Cause: The organization has not accepted the DPA; the live widget stays disabled.
Fix: An owner accepts the DPA in Organization settings → Legal.

Withdrawal function missing

Code: withdrawal_function_missing
Cause: No withdrawal link is configured, so the assistant cannot point shoppers to it.
Fix: Add your store's withdrawal URL in Settings.

Privacy policy missing

Code: privacy_policy_missing
Cause: The widget has no privacy policy link.
Fix: Add your privacy policy URL in Settings.

AI disclosure hidden

Code: ai_disclosure_hidden
Cause: The storefront hides the widget's AI disclosure.
Fix: Remove the CSS or script that hides it; hiding it breaks the AUP.

AI warnings

Azure base model unknown

Code: azure_base_model_unknown
Cause: The Azure deployment's base model could not be matched to the registry.
Fix: Pick the base model in AI settings.

Tools were trimmed

Code: tools_trimmed
Cause: The model's context is too small for every tool.
Fix: Choose a model with a larger context window.

Large knowledge change

Code: knowledge_mass_change
Cause: Many knowledge documents changed at once and wait for review.
Fix: Review the pending changes in Knowledge → Review.

Engagement warnings

Shopper emails suspended

Code: shopper_mail_suspended
Cause: Shopper emails from this store are paused because of bounces or complaints.
Fix: Check your lead and transcript settings; contact support.

Shopper email quota reached

Code: shopper_mail_quota_reached
Cause: The daily shopper email quota is reached.
Fix: Emails resume tomorrow.

Lead sync to the platform failed

Code: lead_sync_failed
Cause: Captured leads could not be synced to your platform.
Fix: Check the platform connection and permissions.

Still stuck?

Contact support from Help in the dashboard and include the sync run id and the request id shown with the error.