Troubleshooting

Updated March 2026

Check for stored consent first

The most common reason: you've already consented in a previous session. Open a private / incognito window and try again. The banner will not appear if localStorage already has a valid, non-expired consent record.

Check the domain allowlist

If you have any domains registered, the SDK will silently do nothing on unregistered hostnames. Open the Domains tab in the Admin UI and confirm your site's hostname is listed. Remember: www.example.com and example.com are treated as separate domains — register both if you use both.

Check your Customer ID

Visit https://cookie-banners-config.onrender.com/config/v1/YOUR_CUSTOMER_ID.json in the browser. If you get a 404, the Customer ID is wrong or the config hasn't been seeded.

Check the script order

Both script tags must appear at the very top of <head>, before any other scripts. If another script loads before the inline snippet, it can't be intercepted.

Check geo rules

If you have an opt-out rule with showBanner: false for your region (e.g. * catch-all), the banner is intentionally suppressed for visitors in that region. The SDK grants all categories silently instead.

Check the browser console

Open DevTools → Console and look for [cc] log lines. A config fetch failure will appear as a warning here. If there are no [cc] lines at all, the snippet isn't running — check that the inline script is present in the page source.

Scripts still loading without consent

Script isn't matched by any rule

Scripts with no matching script rule are treated as essential and released immediately. Go to the Script Scanner tab in the Admin UI, scan your site, and add rules for any uncovered scripts.

Script is declarative and not tagged

The createElement intercept only catches scripts created dynamically via JavaScript. Scripts declared directly in your HTML as <script src="..."> are parsed before the intercept runs. Change them to type="text/plain" with a data-cc-category attribute:

<script
  type="text/plain"
  data-cc-category="analytics"
  src="https://www.googletagmanager.com/gtm.js"
></script>

Script is loading through a tag manager

Scripts injected by GTM or Segment can't be blocked directly — the tag manager itself needs to be blocked. Add a script rule for googletagmanager.com (or your tag manager's domain) under your "Analytics" or "Marketing" category, and change the GTM script tag to type="text/plain".

SDK is failing open

If the config fetch times out (3 seconds), the SDK releases all queued scripts to avoid breaking your site. Check the console for [cc] Config fetch failed, failing open. This is usually caused by the config service being slow to start (Render free tier has cold starts). Consider adding a geo rule so returning visitors don't need to wait for the config.

Scripts blocked after consent

Check the decisions object

Open the browser console and run:

window.__cc.consent
// e.g. { essential: true, analytics: true, marketing: false }

If the relevant category is false, the script is correctly blocked — the user hasn't consented to that category. Ask them to update their preferences.

Config version mismatch

If the stored consent version doesn't match the current config version, the SDK discards stored consent and shows the banner again. This is expected — the user must re-consent after you publish config changes. Check the console for version mismatch messages.

Domain allowlist blocking my site

Hostname not registered

Go to the Domains tab in the Admin UI and add the exact hostname where you're seeing the issue. Common mistakes:

Registered example.com but visiting www.example.com (or vice versa)
Registered example.com but visiting a preview URL like deploy-preview-42.netlify.app

Cache not propagated yet

After adding a domain, the origin cache is cleared immediately. However, if a CDN edge node has a cached copy of your config, it may serve the old allowedDomains list for up to 5 minutes (the CDN max-age). Wait a few minutes and hard-reload the page (Cmd+Shift+R / Ctrl+Shift+R).

Debugging the allowlist check

Fetch your config JSON directly and inspect the allowedDomains array:

https://cookie-banners-config.onrender.com/config/v1/YOUR_CUSTOMER_ID.json

// Look for:
{
  ...
  "allowedDomains": ["example.com", "www.example.com"]
}

If allowedDomains is an empty array, enforcement is inactive (no domains registered). If your hostname is missing from a non-empty list, add it via the Admin UI.

Stale config / old banner copy showing

Config is cached at two layers: Redis at the origin (10 minutes) and the CDN (5 minutes fresh, up to 60 minutes stale-while-revalidate). After saving in the Admin UI, both caches are purged. If you're still seeing old copy:

Hard-reload the page to bypass the browser cache.
Wait up to 5 minutes for CDN edge nodes to propagate.
Check the X-Cache header on the config response — HIT means it's cached, MISS means it fetched fresh from Postgres.

Console errors reference

Message	Cause	Fix
`[cc] No data-cc-id found on script tag.`	The bundle `<script>` tag is missing the `data-cc-id` attribute.	Add `data-cc-id="YOUR_CUSTOMER_ID"` to the bundle script tag.
`[cc] Config fetch failed, failing open.`	The config service didn't respond within 3 seconds.	Check that the Customer ID is valid. Check service health at `/health`.
`POST /v1/consent 403 Forbidden`	The site's hostname is not in the customer's domain allowlist.	Add the hostname in the Domains tab. See Domain Allowlist.
`Access to fetch ... blocked by CORS policy`	The request origin is not allowed by the service's CORS config.	This should not happen with normal usage. Contact support if it persists.