Troubleshooting

When something does not work, this is the page to read first. Common issues across PDP fetch, JSON-LD parsing, webhooks, alerts, and crawler access — each with the diagnostic flow and the fix.

PDP fetch failures

"Unable to fetch" on a SKU means eCommerce Insights's PdpFetcher could not retrieve the page. Three diagnostic steps:

1. Open the SKU detail

   The header strip shows the last fetch attempt timestamp and any error message (HTTP status, timeout, parse failure).

2. Run Agent Lens on the URL

   If GPTBot also returns 403, the issue is on the site (robots.txt or Cloudflare blocking AI crawlers). If GPTBot succeeds but eCommerce Insights fails, the issue is specific to eCommerce InsightsBot.

3. Allow eCommerce InsightsBot in robots.txt

   Add User-agent: eCommerce InsightsBot with Allow: /. Or whitelist our IP range in Cloudflare. Both documented in Settings → Crawler.

Cloudflare and bot challenges

Cloudflare's bot-fight mode aggressively challenges automated user-agents. eCommerce Insights falls back to ScrapingBee on 403 / CF challenge responses (added in v14). The fallback is transparent and the score is computed regardless of which fetcher succeeded.

If both fail, the page is genuinely inaccessible to non-browser clients. Two fixes:

• Add eCommerce Insights's IP range to your Cloudflare whitelist (IP list in Settings → Crawler).
• Disable bot-fight mode for the product subdirectory. Most stores can do this without losing protection on the rest of the site.

JSON-LD parse errors

v14 added handling for two common JSON-LD edge cases:

• Array-wrapped JSON-LD. Some platforms wrap their script content in an array. eCommerce Insights's PdpParser now unwraps these correctly.
• Unescaped control characters. A bug we called "the RobotShop fix" — descriptions containing literal newlines inside JSON strings used to fail parse. Now handled.

If your JSON-LD still fails to parse, run Agent Lens on the URL. The structured-data inventory will show the exact parse error with line and column. Most remaining failures are HTML-entity-escaped quotes inside JSON strings — fix the source.

Webhooks not arriving

Shopify webhooks: verify registration in Shopify admin → Settings → Notifications → Webhooks (look for entries with ecommerceinsights in the URL). If absent, reinstall the integration.

WooCommerce webhooks: WooCommerce → Settings → Advanced → Webhooks. If status is Disabled, click to re-enable.

Outbound webhooks from eCommerce Insights (API): check the webhook log in Settings → Integrations → API. Failed deliveries are retried with backoff.

Alerts not firing

1. Confirm the rule is Enabled (toggle in Settings → Alerts).
2. Confirm the rule's scope includes the affected SKU (tag, category, or explicit SKU list).
3. Confirm the threshold is set correctly. Score-drop rules with a threshold of 90 will rarely fire if your average score is 65.
4. For Slack: re-issue the incoming webhook URL. Slack incoming webhooks expire when the workspace owner revokes the app.
5. For Email (Resend): verify RESEND_API_KEY in Settings is current.

Scores appear stale

Open the Schedule page. Each task shows its last-run timestamp. If a task hasn't run, either the cadence is longer than expected or the scheduler is stuck.

Hit "Run scheduler now" to force every due task. If the task still doesn't progress, hit the cron-tick endpoint manually as a fallback: GET /?api=cron_tick.

Contacting support

Email [email protected] with workspace ID, affected SKU, and a screenshot of the error. Typical response time is a few hours during business hours (US/Eastern).

Common questions