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

# Troubleshooting & FAQ

> Common issues and answers for OpenHermit users.

## Installation

<AccordionGroup>
  <Accordion title="I pasted the script but the dashboard still shows 'Script not yet detected'">
    Work through this checklist:

    **1. Check the script is actually on the page**
    Press `Ctrl+U` (Windows) or `Cmd+U` (Mac) in your browser to view the raw HTML source. Search for `openhermit` — the script tag should appear near the bottom, before `</body>`.

    **2. Check the API key is correct**
    Compare the `data-api-key` in your HTML with the key shown in your dashboard. They must match exactly.

    **3. Check the browser console**
    Open DevTools (F12) → Console. Look for any errors related to `script.js`. If you see `No data-api-key found`, the attribute is missing or misspelled.

    **4. Check for Content Security Policy (CSP) blocks**
    If your site has a strict CSP, it may block the script from loading or making requests to `openhermit.com`. You'll see a CSP error in the Console. Add `https://openhermit.com` to your `script-src` and `connect-src` directives.

    **5. Visit the page in a browser**
    The script runs in the visitor's browser — it doesn't run during server-side rendering. Open the page in a real browser (not just deploy it) and the ping will fire.
  </Accordion>

  <Accordion title="The script is detected but no actions appear">
    The script confirmed it's running (ping is working) but found no forms on that specific page.

    * **The form is on a different page.** Visit the page that actually contains the contact form, booking widget, etc. The script scans one page at a time.
    * **The form loads dynamically.** React/Vue/Angular apps render forms after the initial HTML. Wait 2–3 seconds after the form appears, then check the dashboard.
    * **The form isn't a real `<form>` element.** Some builders (Webflow, custom React components) use `div` and `onClick` instead of `<form>` and `<input>`. The script can't detect these automatically. See [Manual detection](/guides/installation-verification#adding-detection-manually).
  </Accordion>

  <Accordion title="I'm using Next.js and the script isn't detecting forms">
    In Next.js, use `strategy="afterInteractive"` — not `lazyOnload` or `beforeInteractive`:

    ```tsx theme={null}
    <Script
      src="https://openhermit.com/script.js"
      data-api-key="YOUR_KEY"
      strategy="afterInteractive"
    />
    ```

    `afterInteractive` runs after React hydration, which means the page's forms are already in the DOM when the script scans. `lazyOnload` waits too long on fast connections and can miss forms.

    Also make sure the Script component is in your **root layout** (`app/layout.tsx`), not just on one page.
  </Accordion>

  <Accordion title="The script is on my homepage but I have forms on other pages">
    The script should be on **every page** of your website — ideally added once to your global layout or template, not per-page.

    * **Next.js:** Add to `app/layout.tsx`
    * **WordPress:** Add via `functions.php` with `wp_footer` hook
    * **Webflow/Squarespace:** Use the platform's "Footer Code" setting — this adds it globally
    * **HTML sites:** Copy the script tag into every HTML file's `</body>` section
  </Accordion>
</AccordionGroup>

***

## Form detection

<AccordionGroup>
  <Accordion title="My contact form was detected but the wrong type was assigned">
    The script classifies forms by scanning the HTML for keyword signals. If your form has unusual labels or is in a non-English language, it may be misclassified.

    You can override the type by adding a `data-mcp-action` attribute to your `<form>` element:

    ```html theme={null}
    <form data-mcp-action="contact_form" id="kontakt-form">
      ...
    </form>
    ```

    Valid types: `contact_form`, `booking`, `newsletter`, `signup`, `purchase`, `quote`, `login`, `search`, `upload`, `support`
  </Accordion>

  <Accordion title="My Calendly / Typeform / HubSpot form isn't being detected">
    Third-party widgets are detected by checking for their JavaScript objects or DOM elements. Make sure:

    * **Calendly:** The Calendly widget script has fully loaded before OpenHermit runs. If Calendly loads slowly, the detection may miss it. The MutationObserver will re-scan when new content appears, so it usually self-corrects within a second.
    * **HubSpot:** The `window.hbspt` object must be present. If HubSpot is loaded via Google Tag Manager with a delay, the detection may miss it.
    * **Typeform:** The embed must use a `<div data-tf-widget>` element or a `tf-widget` element.

    If automatic detection fails, add `data-mcp-action` attributes manually to the container element of the widget.
  </Accordion>

  <Accordion title="The action name detected is wrong or unclear">
    The script tries to name forms from: aria-label → legend text → nearest heading → form ID → form class. If none of these are clear, it falls back to the form type.

    Fix it by editing the action name directly in your dashboard under **Actions → Edit Prompts**, or add an `aria-label` to your form:

    ```html theme={null}
    <form aria-label="Book a Free Consultation">
    ```
  </Accordion>
</AccordionGroup>

***

## Agent prompts

<AccordionGroup>
  <Accordion title="I configured prompts but agents aren't seeing them">
    Prompts are delivered two ways. Check both:

    **Via the manifest:** Fetch your manifest directly and confirm the prompts appear:

    ```
    https://openhermit.com/api/manifest?key=YOUR_API_KEY
    ```

    **Via the DOM:** View the page source after the script loads. Search for `WebMCP Agent Instructions` — you should see a hidden div with your prompts.

    If prompts appear in the manifest but not in the DOM, the script may not be re-running after you saved the prompts. Clear your browser cache and reload the page.
  </Accordion>

  <Accordion title="Can I use different prompts for different pages?">
    Currently, prompts are set per action (not per page). If the same form appears on multiple pages, it shares the same prompts.

    If you need different prompts for the same type of form on different pages, create a second website entry in the dashboard for that specific subdomain or section.
  </Accordion>
</AccordionGroup>

***

## Analytics

<AccordionGroup>
  <Accordion title="Why do I see 0 interactions even though agents are visiting?">
    Agent interactions are only tracked when:

    1. The visiting agent's user-agent string matches a known AI agent pattern (GPTBot, ClaudeBot, etc.)
    2. The agent submits a form or triggers a tracked event

    Most AI agents that browse via screenshots (computer use) don't identify themselves in the user-agent string. OpenHermit only tracks agents that make standard HTTP requests — not headless browser automation.
  </Accordion>

  <Accordion title="I see 'Unknown agent' in my interactions">
    The agent's user-agent string didn't match any known pattern. This can happen with:

    * Custom or internal agent tools
    * New agents not yet in our detection list
    * Agents that spoof a regular browser user-agent

    The interaction is still tracked — it just shows as Unknown.
  </Accordion>
</AccordionGroup>

***

## Account & billing

<AccordionGroup>
  <Accordion title="What's included in the free plan?">
    The free plan includes:

    * 1 website
    * Contact form detection only
    * Up to 1,000 agent interactions per month
    * Basic analytics

    Upgrade to Pro for unlimited websites, all action types, and full analytics.
  </Accordion>

  <Accordion title="Can I delete a website and add it again?">
    Yes. Deleting a website removes all its actions and events permanently. If you re-add the same domain, it starts fresh with a new API key. You'll need to update the script tag on your website with the new key.
  </Accordion>
</AccordionGroup>