Troubleshooting
Find your symptom below, check the likely cause, then follow the linked fix. If nothing here matches, write to [email protected].
Banner does not appear
| Likely cause | Fix |
|---|---|
| The head snippet is missing | Add the script tag in <head>. See direct snippet install |
| Installed through GTM only, without the head loader | A GTM-only install can miss the head loader. Add the direct head snippet. See Google Tag Manager install and direct snippet install |
| Safari Private browsing blocks a GTM-delivered banner | Safari Private blocks the GTM domain. A banner delivered through GTM never loads. Add the direct head snippet to load the banner first-party. See direct snippet install |
| An ad blocker is blocking the script | Confirm in the Network tab. Test with the ad blocker off. See verify installation |
window.OptSens is undefined | The script did not load. Work through debugging |
| The Domain ID was regenerated | The old ID stops working immediately. Update the new ID in your snippet and every integration. See API and webhooks |
| The domain's subscription is inactive | A cancelled, expired or suspended subscription stops the banner from loading. Check the domain on Billing |
Banner shows, but tags fire before consent
| Likely cause | Fix |
|---|---|
| Auto-blocking has not been configured for those tags | The script blocks scripts the scanner detected on your site. Run a scan and confirm coverage. See auto-blocking |
| Inline or custom scripts are not tagged | Tag them to make them wait for consent. See manual tagging |
| Google tags (GTM or GA4) load before consent | By design OptSens does not block Google tags. They are held by Google Consent Mode, which stays denied until consent, and they do not set cookies or fire tags before then. This is expected. See Consent Mode v2 |
Scan finds no cookies
| Likely cause | Fix |
|---|---|
| A WAF or bot protection is blocking the scanner | The scanner is refused before it can read the page. Allow the OptSens scanner. See bot and scanner access |
See the scanner overview for how scanning works.
Google Consent Mode check fails
| Likely cause | Fix |
|---|---|
| Consent Mode signals are not detected | Review what the check looks for and how to fix it. See GCM check |
Styling looks wrong
| Likely cause | Fix |
|---|---|
| Custom styles are not reaching the banner | By design the banner renders in Shadow DOM and your page styles cannot reach it. Use the theme, color and font controls in the banner editor. Full custom CSS is coming soon |
| The banner does not match your page font size | The banner uses fixed pixel font sizes and does not inherit the page. Set the font family in the banner editor, or leave it on inherit to match your site |
| A strict Content Security Policy blocks the banner styles | Pass your per-request nonce to the OptSens script so its styles are allowed. See CSP nonce |
Webhook signature checks fail
| Likely cause | Fix |
|---|---|
| The signed string or header format is off | Sign timestamp + "." + body with the webhook secret as a hex HMAC-SHA256, then compare against X-OptSens-Signature, which carries a v1= prefix. See API and webhooks |
More help
| Topic | Page |
|---|---|
| Confirm the install | Verify installation |
| Install-specific problems | Install troubleshooting |
| Inspect consent from the console | Debugging |