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

# Troubleshooting

> Why your AI CMO might fail to set up, and how to fix it.

When you add a website to Okara, we fetch and analyze your site to build your AI CMO. If something goes wrong during that process, here's how to diagnose and fix it.

***

## Common reasons for failure

<AccordionGroup>
  <Accordion title="Website could not be reached">
    Okara tries to fetch your site at the URL you entered. If the site is unreachable, the setup will fail with a message like:

    > *"That website could not be reached."*

    **What to try:**

    1. Make sure the site is publicly accessible (not behind a login, VPN, or maintenance page)
    2. Confirm the domain is live and your DNS is resolving correctly
    3. If your site is hosted behind a WAF or CDN (Cloudflare, Fastly, etc.), it may be blocking OkaraBot — see [Whitelisting OkaraBot](#whitelisting-okarabot) below
  </Accordion>

  <Accordion title="Invalid URL format">
    Okara only accepts top-level domains or one level of path. Deep paths are not supported.

    | Accepted           | Not accepted             |
    | ------------------ | ------------------------ |
    | `okara.ai`         | `www.okara.ai`           |
    | `okara.ai/product` | `okara.ai/blog/post/123` |

    Do not include `https://`, query strings (`?ref=...`), or fragments (`#section`).
  </Accordion>

  <Accordion title="Content could not be extracted">
    Okara reads your page's HTML to understand your business. If we can't extract enough content, setup will fail.

    **What to try:**

    * Check that your homepage has readable text in its page source (right-click → View Page Source)
    * Check your `robots.txt` — if it blocks all crawlers, OkaraBot won't be able to read the page
  </Accordion>

  <Accordion title="Plan or slot limit reached">
    * Your first website is included on all plans
    * Adding a second website requires an active **Max plan**
    * Additional slots beyond that require purchasing an add-on

    Visit [okara.ai/pricing](https://okara.ai/pricing) to upgrade or add a slot.
  </Accordion>
</AccordionGroup>

***

## Whitelisting OkaraBot

If your site sits behind a WAF (Web Application Firewall) or CDN, it may be blocking OkaraBot's requests. Whitelist the following user agent string to allow it through:

```
Mozilla/5.0 (compatible; OkaraBot/1.0; +https://okara.ai/bot)
```

<AccordionGroup>
  <Accordion title="Cloudflare">
    1. Go to your Cloudflare dashboard and select your domain
    2. Navigate to **Security > WAF > Custom Rules**
    3. Create a rule with:
       * **Field:** User Agent
       * **Operator:** contains
       * **Value:** `OkaraBot`
    4. Set the action to **Allow**
    5. Save and deploy the rule
  </Accordion>

  <Accordion title="AWS WAF">
    1. Open the AWS WAF console and select your Web ACL
    2. Add a rule with a string match condition on the `User-Agent` header containing `OkaraBot`
    3. Set the rule action to **Allow** and place it before any block rules
  </Accordion>

  <Accordion title="Sucuri / other WAFs">
    Look for a **Whitelist** or **Allowlist** section in your WAF dashboard. Add `OkaraBot` as an allowed user agent string. Refer to your WAF provider's documentation for exact steps.
  </Accordion>

  <Accordion title="robots.txt">
    If your `robots.txt` blocks all bots, add an explicit allow for OkaraBot:

    ```
    User-agent: OkaraBot
    Allow: /
    ```
  </Accordion>
</AccordionGroup>

<Info>
  If you need IP ranges to whitelist or have questions, email [support@okara.ai](mailto:support@okara.ai) with your domain name.
</Info>

***

## Onboarding failed after the website was accepted

Sometimes the initial URL check passes but onboarding fails during analysis. Okara retries automatically up to 3 times. If it's still failing:

1. Wait about an hour — a **Retry** button will appear on your dashboard
2. Click **Retry** to resume from where it left off
3. If retrying doesn't help, contact [support@okara.ai](mailto:support@okara.ai) with your agent ID

<Card title="Learn more about OkaraBot" icon="robot" href="https://okara.ai/bot">
  See the OkaraBot info page for full details on how the crawler works and what it accesses.
</Card>