The pixel is not detected
Symptoms: Health shows No sessions received. The verification in Settings > Pixel Setup stays incomplete. Check these in order:- 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. - Caches are cleared. Clear your caching plugin, server cache and CDN cache, then reload the page in a private window.
- The measurement ID is yours. The
data-idvalue must match the measurement ID under Settings > Organization. Events with an unknown measurement ID are rejected. Never copy a script from another organization. - The script is not changed. Use the script exactly as Octanist shows it. Do not change the
srchost. A custom domain only works once Settings > DNS Setup shows it as active. - 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.
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.
c.octani.st host. See DNS setup.
Forms are not captured
Symptom: Health shows Pageviews but no form submissions. For the tracking pixel:- The script must have the
data-formsattribute 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-adminor/wp-login.php. - Paths that start with
/checkout,/cart,/basketor/payment, unless the script hasdata-checkout="true". - Forms with a password field.
- Forms with the
data-octa-ignoreattribute.
- Paths that start with
- 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.
- 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.
Form submissions arrive, but no leads are created
Check these in order:- 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.
- 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.
- The form is not ignored. Forms you ignored in Settings > Forms, and forms that match an ignore rule, are dropped.
- The domain is allowed. See Leads are rejected by domain filtering.
- You are within your lead limit. See Leads are missing after the plan limit.
Leads are rejected by domain filtering
Symptoms: Leads from one website never appear. The API returns403 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.commatcheswww.example.comandshop.example.com.
sessionId, otherwise from the website field. See Lead filtering.
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.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-ignoreto that form, or removedata-formsfrom 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 sendsessionIdfrom your backend. See Server-side form capture. - 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
gclidparameter 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.
Conversions are not uploaded
Open the lead and go to History. Each upload, skip and failure is listed with its reason.
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.
- 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.
API errors
PATCH /api/leads returns 200 with "matched": false when no lead matches. See the API reference.