> ## Documentation Index
> Fetch the complete documentation index at: https://docs.merchantai.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting common MerchantAI setup and widget issues

> Step-by-step fixes for the most common MerchantAI issues — agent setup, widget deployment, knowledge indexing, handover configuration, and billing.

Most issues with MerchantAI fall into a small number of categories: something wasn't indexed correctly, a script didn't load as expected, or a configuration setting needs adjusting. The sections below walk through the most common problems and their fixes. Work through the relevant steps before reaching out to support — in most cases, you'll be unblocked quickly.

***

### Agent Setup

<Accordion title="Website pages aren't being indexed">
  If pages from your site aren't appearing in your knowledge base after a crawl, check the following:

  1. **Confirm the URL is publicly accessible.** The MerchantAI crawler cannot access pages behind a login, staging password, or VPN. Verify you can open the URL in an incognito browser without signing in.
  2. **Trigger a manual re-crawl.** Go to **Knowledge → Website** in your dashboard and select **Re-crawl**. This forces a fresh pass and updates the indexed content.
  3. **Check your `robots.txt`.** If your site's `robots.txt` blocks unknown crawlers, add the MerchantAI crawler user-agent to the allow list.

  <Tip>
    Pages added or updated after your last crawl won't appear automatically — trigger a manual re-crawl after significant content changes.
  </Tip>
</Accordion>

<Accordion title="The Shopify app didn't sync my products">
  If your Shopify catalogue isn't appearing in the knowledge base after installation, follow these steps:

  1. **Check permissions.** During Shopify app installation you're prompted to approve required permissions. If any were declined, the sync cannot complete. Review the app's permission status in your Shopify admin.
  2. **Trigger a manual re-sync.** In your MerchantAI dashboard, navigate to **Knowledge → Shopify** and select **Re-sync**.
  3. **Reinstall the app if the issue persists.** Remove MerchantAI from your Shopify admin and reinstall from the App Store. This resets the OAuth token and resolves most persistent sync failures.
</Accordion>

<Accordion title="I can't find my workspace after signing in">
  If your dashboard appears empty or a workspace isn't visible after logging in:

  * **Confirm you're using the correct sign-in method.** If you signed up via Shopify, you must log in using the same Shopify account — not a separate email/password combination.
  * **Check for duplicate accounts.** You may have created the workspace under a different email address.
  * **Contact support.** If you're confident you're using the right account and the workspace still isn't visible, contact the support team with your sign-up email.
</Accordion>

***

### Widget & Deployment

<Accordion title="The widget isn't appearing on my site">
  If the MerchantAI widget doesn't show up on your website after installation:

  1. **Verify script placement.** The snippet must be placed before the closing `</body>` tag on every page where you want the widget to appear.
  2. **Check the browser console for errors.** Open your browser's developer tools and look for script errors related to `widget.merchantai.io`.
  3. **Review your Content Security Policy (CSP).** If your site uses a CSP header, add `widget.merchantai.io` to the `script-src` directive.

  <Warning>
    If you're using a tag manager (e.g. Google Tag Manager), make sure the MerchantAI snippet fires on all relevant pages and is not blocked by trigger conditions.
  </Warning>
</Accordion>

<Accordion title="The widget appears but the agent doesn't respond">
  If the widget loads but messages receive no reply:

  * **Message limit reached.** If you've hit your monthly message allocation, the agent stops responding until the next billing period. Check your usage in the dashboard. Upgrading your plan restores your allocation immediately.
  * **Empty or unapproved knowledge base.** The agent requires at least one approved source. Go to **Knowledge** and confirm at least one source has been crawled and approved.
</Accordion>

<Accordion title="Widget loads slowly">
  The MerchantAI widget loads asynchronously and should not block page rendering. If you're experiencing slowdowns:

  * **Check for conflicts with other chat tools.** If another chat widget is running on the same page, try disabling it temporarily to isolate the issue.
  * **Review third-party script load order.** Heavy analytics or personalisation scripts that load synchronously before `</body>` can delay all subsequent scripts.
</Accordion>

***

### Knowledge & Answers

<Accordion title="The agent is giving outdated information">
  If the agent is surfacing prices, product details, or policies that no longer reflect your store:

  * **Trigger a manual re-crawl or re-sync** from the **Knowledge** dashboard.
  * **Check Shopify webhook delivery.** Go to your Shopify admin and confirm webhooks are being delivered without errors. Failed webhooks mean automatic updates aren't reaching MerchantAI.
</Accordion>

<Accordion title="The agent says it doesn't know something I've documented">
  If the agent can't answer a question that's clearly covered in your content:

  1. **Source approval status.** Navigate to **Knowledge** and confirm the page, file, or Q\&A pair is marked as approved. Unapproved sources are excluded from the agent's knowledge.
  2. **Confidence threshold setting.** If the threshold is set too high, the agent may decline to answer even with relevant content. Review and adjust in **Configuration → Guardrails**.
</Accordion>

<Accordion title="The agent is discussing topics I've blocked">
  If the agent is engaging with a topic you intended to block, check **Configuration → Guardrails → Topic controls**:

  * **Confirm the topic is in your blocklist.** Re-add it and save if needed.
  * **Check keyword spelling and variants.** Keyword-based blocks are matched exactly. If the topic can be expressed multiple ways (e.g. "refund", "refunds", "money back"), add each variant explicitly.

  <Tip>
    For broad topic categories, use topic-level controls rather than individual keywords — they're more reliable and easier to maintain.
  </Tip>
</Accordion>

***

### Handover & Contacts

<Accordion title="I'm not receiving handover emails">
  If your team isn't getting email notifications when a conversation is escalated:

  1. **Verify the configured address.** Go to **Configuration → Handover** and confirm the email address is correct.
  2. **Check spam and junk folders.** Transactional emails from MerchantAI may be filtered by your provider.
  3. **Check domain-level email filtering.** Ask your IT team to whitelist transactional emails from MerchantAI's sending domain if needed.
</Accordion>

<Accordion title="The Contacts inbox is empty">
  If no leads or conversations are appearing in your Contacts inbox:

  * **Plan eligibility.** Lead capture and the Contacts inbox are available on the **Pro plan and above**. Upgrade to Pro to enable this feature.
  * **Lead capture configuration.** Lead capture must be explicitly enabled. Go to **Configuration** and confirm that lead capture is toggled on.
</Accordion>

***

### Billing

<Accordion title="I was charged but thought I was on a free trial">
  Paid plan trials run for exactly 14 days from the moment you subscribe. Your card is charged automatically on day 15 if you haven't cancelled. To check when your trial started, go to **Settings → Billing** in your dashboard.

  <Warning>
    If you signed up via Shopify, billing is managed through your Shopify admin. Check your Shopify billing page for the charge details.
  </Warning>
</Accordion>

<Accordion title="My plan downgrade hasn't taken effect">
  Downgrades are applied at the **end of your current billing cycle**, not immediately. You retain all features of your existing plan until the cycle ends. This is by design — you keep access to what you paid for until the period expires.
</Accordion>

***

<Note>
  If none of the steps above resolve your issue, contact the MerchantAI support team from the **Help** menu in your dashboard. Include a description of the problem, your workspace ID, and any relevant error messages or screenshots.
</Note>