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

# Common issues

> Fixes for the most common Octanist problems: pixel not detected, no sessions, forms not captured, leads not created, leads rejected by domain filtering, missing click IDs, conversions not uploaded, lead updates not applied and API errors.

Start with **Settings > Health** ([Tracking health](https://octanist.com/docs/settings/tracking-health.md)). It shows sessions, page views, form submissions, form leads, click ID coverage and consent over the last 24 hours. It also lists open issues, such as forms that need mapping, with a link to the fix.

For a website install, the [Octanist Debugger](https://octanist.com/docs/troubleshooting/octanist-debugger.md) Chrome extension shows what the pixel sees on a page.

## The pixel is not detected

**Symptoms:** Health shows **No sessions received**. The verification in **Settings > Pixel Setup** stays incomplete.

Check these in order:

1. **The script is live.** Open the website, view the page source, and search for `data-id="OCT-`. If it is missing, the script is not published. Publish the site or the GTM container again.
2. **Caches are cleared.** Clear your caching plugin, server cache and CDN cache, then reload the page in a private window.
3. **The measurement ID is yours.** The `data-id` value must match the measurement ID under **Settings > Organization**. Events with an unknown measurement ID are rejected. Never copy a script from another organization.
4. **The script is not changed.** Use the script exactly as Octanist shows it. Do not change the `src` host. A custom domain only works once **Settings > DNS Setup** shows it as active.
5. **You use the test link.** The test link on **Settings > Pixel Setup** opens your website with a test click ID. Let the page load completely and stay in the same browser visit.

On WordPress, also check that the setup code is saved under **Settings > Octanist** in WordPress. See [WordPress](https://octanist.com/docs/incoming-integrations/wordpress.md).

## Sessions arrive, but no page views

**Symptom:** Health shows **Sessions but no pageviews**.

Open the website with the Octanist Debugger and check the **Events** tab. Make sure the full script is installed on every page, not only on some of them. If it still fails, send the debugger report to support.

## The custom tracking domain is pending or failed

**Symptom:** **Settings > DNS Setup** or Health shows the domain as pending or failed.

* Add the CNAME record exactly as shown in **Settings > DNS Setup**.
* If your DNS runs on Cloudflare, set the record to **DNS only** (grey cloud), not proxied (orange cloud). Otherwise the certificate validation fails.
* DNS and SSL can take time. Check the status again later.

Until the domain is active, keep using the script with the default `c.octani.st` host. See [DNS setup](https://octanist.com/docs/incoming-integrations/dns-setup.md).

## Forms are not captured

**Symptom:** Health shows **Pageviews but no form submissions**.

For the tracking pixel:

* The script must have the `data-forms` attribute for browser form detection. In **Settings > Pixel Setup**, set **Listen to forms** to on and copy the script again.
* Browser detection skips some pages and forms on purpose:
  * Paths that start with `/login`, `/signin`, `/sign-in`, `/register`, `/signup`, `/sign-up`, `/account`, `/my-account`, `/admin`, `/dashboard`, `/wp-admin` or `/wp-login.php`.
  * Paths that start with `/checkout`, `/cart`, `/basket` or `/payment`, unless the script has `data-checkout="true"`.
  * Forms with a password field.
  * Forms with the `data-octa-ignore` attribute.
* A form that fails the browser's own validation is not sent.
* Forms inside an iframe are not supported. Contact support for these.
* Custom JavaScript forms that never submit a normal form need the [Client-side API](https://octanist.com/docs/incoming-integrations/client-side-api.md).

For WordPress:

* Supported form plugins are captured server-side. Check that you chose the right form plugin in **Settings > Pixel Setup** and pasted the new setup code.
* Forms built in your own theme or plugin code need [one line of PHP](https://octanist.com/docs/incoming-integrations/wordpress.md#custom-forms).

See [Tracking pixel](https://octanist.com/docs/incoming-integrations/pixel.md#form-capture) for all capture rules.

## Form submissions arrive, but no leads are created

Check these in order:

1. **The form is mapped.** A new form waits in **Settings > Forms** until you confirm its field mapping. Health shows **Form submissions need mapping**. After you map the form, earlier submissions are converted to leads too. See [Form mapping](https://octanist.com/docs/incoming-integrations/form-mapping.md).
2. **The mapping has an identifier.** At least one mapped field must be a name, email, phone or external lead ID. Submissions without any of these are rejected.
3. **The form is not ignored.** Forms you ignored in **Settings > Forms**, and forms that match an ignore rule, are dropped.
4. **The domain is allowed.** See [Leads are rejected by domain filtering](#leads-are-rejected-by-domain-filtering).
5. **You are within your lead limit.** See [Leads are missing after the plan limit](#leads-are-missing-after-the-plan-limit).

## Leads are rejected by domain filtering

**Symptoms:** Leads from one website never appear. The API returns `403 FORBIDDEN` with `Lead rejected by filtering rules`.

**Settings > Lead Filtering** can limit leads to some domains:

* With an **allowlist**, only leads from listed domains are accepted. Leads without a known website are rejected too.
* With a **blocklist**, leads from listed domains are rejected.
* A domain also matches its subdomains. `example.com` matches `www.example.com` and `shop.example.com`.

Add the missing domain, or turn lead filtering off. For API leads, the website comes from the pixel session when you send `sessionId`, otherwise from the `website` field. See [Lead filtering](https://octanist.com/docs/settings/lead-filtering.md).

## Leads are missing after the plan limit

Each plan includes a number of leads per month. Leads above that number are still stored, but they are locked. Locked leads do not show in the app or the API until you upgrade. **Settings > Billing** shows your usage. See [Billing and plans](https://octanist.com/docs/settings/billing-and-plans.md).

## Duplicate leads

* Use one capture method per form. Do not send the same form through the pixel, the WordPress plugin, GTM DataLayer, Zapier and the API at the same time.
* When a backend or script already sends a form, add `data-octa-ignore` to that form, or remove `data-forms` from the pixel.
* Octanist already merges the same lead sent twice within one minute with the same contact details. Leads with the same external lead ID are never duplicated.

## Leads have no click ID or campaign

* **The lead has no session.** Leads sent through the API without `sessionId`, or through GTM DataLayer, only have the attribution sent with them. Install the pixel and send `sessionId` from your backend. See [Server-side form capture](https://octanist.com/docs/incoming-integrations/server-side-capturing.md).
* **Google Ads is connected, but no click IDs arrive.** Health shows **Google Ads connected but no Google click IDs captured**. Check that auto-tagging is on in Google Ads, and that your landing pages keep the `gclid` parameter in the URL after redirects.
* **The pixel loads on a different domain.** Install the pixel on every domain that receives ad traffic, not only on the domain with the form.

## Consent stays denied

* In **Auto** mode, Octanist follows your consent banner. It reads Cookiebot, CookieYes, Complianz, IAB TCF and GPP, the WordPress Consent API and Google Consent Mode in the dataLayer.
* With visitors from regions that require consent and no banner, Auto keeps most storage denied until consent is given.
* If your banner is not detected, send consent yourself with `window.OCT.setConsent()`. See [Client-side API](https://octanist.com/docs/incoming-integrations/client-side-api.md#update-consent-manually).

See [Consent mode](https://octanist.com/docs/user-consent/consent-mode.md).

## Conversions are not uploaded

Open the lead and go to **History**. Each upload, skip and failure is listed with its reason.

| Reason in History | What to do |
| - | - |
| No active subscription | Choose a plan under **Settings > Billing**. |
| Not available on your plan | Meta, Microsoft Ads, LinkedIn, TikTok, Snapchat, Google Analytics 4 and BigQuery need the Professional plan or higher. GTM Server needs Advanced. |
| No Google click ID found and "Send all leads" is disabled | The lead has no `gclid`, `wbraid` or `gbraid`. Turn on **Send all leads** in the Google Ads integration to also send leads without a click ID. |
| gclid is from SA360, not Google Ads | The click came from Search Ads 360. It cannot be uploaded to Google Ads. |
| No Meta Click ID found and "Send all leads" is disabled | The lead has no Meta click ID. Turn on **Send all leads** in the Meta integration to send it anyway. |
| The click is too old for this conversion | Ad platforms only accept conversions for recent clicks, usually up to 90 days. Qualify leads sooner. |
| Missing permission | Reconnect the integration with an account that has access to the ad account. |

Also check:

* **The integration was connected after you qualified the lead.** Meta and Google Analytics do not accept conversions after the fact.
* **The conversion name matches.** The conversion name in **Settings > Conversions** must match the conversion action in your ad platform exactly. See [Conversions](https://octanist.com/docs/settings/conversions.md).
* **The lead is won with a value.** A lead can only be won with a value above 0.

## Lead updates from a CRM or the API are not applied

* **No lead matched.** The update matches by Octanist ID, external lead ID, email, then phone. An update with a status that finds no lead is kept for 30 days. It is applied when a matching lead arrives within that time.
* **The status cannot change.** Status changes go forward only. Won and lost leads do not change through updates. A qualified lead cannot be qualified again.
* **Won without a value.** Send a value above 0, or set one on the lead first.
* **Several leads matched.** **Settings > Lead Updates** decides what happens: update the most recent lead, the first lead, all leads, split the value, or return an error.

The lead's **History** shows skipped and failed updates. See [Lead updates](https://octanist.com/docs/settings/lead-updates.md).

## API errors

| Status | Code | Cause and fix |
| - | - | - |
| 401 | `UNAUTHORIZED` | The `X-API-KEY` header is missing or the key is invalid or revoked. Create a key under **Settings > API / MCP**. |
| 400 | `VALIDATION_ERROR` | The body is not valid JSON, a field has the wrong type, or no identifier was sent. The `details.errors` array names the field. |
| 400 | `VALIDATION_ERROR`, `Invalid or unknown sessionId` | The session ID does not exist for your organization. Check that the pixel on the page uses your measurement ID. |
| 403 | `FORBIDDEN` | Lead filtering rejected the lead, or the organization is a read-only demo. |
| 409 | `CONFLICT` | The external ID belongs to a lead with other contact details, several leads match and your settings return an error, or the lead changed during the update. |

`PATCH /api/leads` returns `200` with `"matched": false` when no lead matches. See the [API reference](https://octanist.com/docs/api-reference/introduction.md).

## Still stuck?

Email [support@octanist.com](mailto:support@octanist.com). Include the website URL and, for install problems, the report from the [Octanist Debugger](https://octanist.com/docs/troubleshooting/octanist-debugger.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.