Troubleshooting Playbook

Last updated: February 21, 2026

This playbook provides symptom -> cause -> verification -> fix guidance.

1. Banner Not Showing

Symptoms:

no banner visible on first visit

Root causes:

invalid settings ID

script blocked by CSP or ad blocker

loader script placed too late or removed by optimizer

How to confirm:

Fix:

verify settings ID

allowlist required domains

ensure script is present exactly once in page source

Symptoms:

analytics/ads tags execute before consent configuration

Root causes:

CMP tag not on Consent Initialization trigger

duplicate tag configuration

How to confirm:

Fix:

move CMP tag to Consent Initialization

remove conflicting consent commands

Symptoms:

user interacts with banner but no update seen

Root causes:

JS error interrupts callback

blocked network request

stale cached script

How to confirm:

check browser console errors

inspect network requests to CMP API endpoint

Fix:

resolve runtime errors

clear cache and republish

validate API reachability

4. Duplicate Banner

Symptoms:

two banners appear

Root causes:

plugin + manual script both active

theme embed + app embed both enabled

How to confirm:

Fix:

keep only one integration path

5. TCF API Missing

Symptoms:

window.__tcfapi undefined

Root causes:

script not loaded

broken execution order

blocked third-party resource

How to confirm:

Fix:

verify script and CSP

validate page-level script ordering

6. What to Send Support

Settings ID

production URL

screenshots

console output

debug report from NexaGuard Debug Tool

7. iOS Pod Version Not Found Right After Release

Symptoms:

CocoaPods could not find compatible versions for pod "NexaGuardSDK"

requested latest version exists in Trunk but not in local resolver/search yet

Root causes:

CocoaPods CDN propagation delay for newly released version

How to confirm:

Fix:

run pod install --repo-update (or pod repo update trunk)

if still delayed, temporarily pin by Git tag in Podfile:

once CDN catches up, switch back to standard version pin

8. Android SDK Version Not Found Right After Release

Symptoms:

Could not find com.nexaguard:nxg-sdk:x.y.z

newly released version is visible in Sonatype Central but not yet resolvable in local Gradle build

Root causes:

Maven Central index/metadata propagation delay

local Gradle dependency cache still resolving stale metadata

How to confirm:

Fix:

sync Gradle project and rerun build with dependency refresh:

ensure repository order includes mavenCentral() in project settings

if still delayed, retry after propagation window

9. Sonatype Close Fails: Component Already Exists

Symptoms:

closeSonatypeStagingRepository fails with:
Component with package url ... already exists

Root causes:

attempting to publish a version that was already released (Maven Central versions are immutable)

How to confirm:

Sonatype close task returns HTTP 400 with already exists for pkg:maven/com.nexaguard/[email protected]

Fix:

bump SDK version in cmp-sdk/build.gradle.kts

publish again with the new version

Symptoms:

banner actions work visually but wp_has_consent(...) does not reflect expected category states

Root causes:

WP Consent bridge not loaded or blocked

WP Consent API functions unavailable in runtime

category payload mismatch from custom integration overrides

How to confirm:

Fix:

ensure nexaguard-cmp plugin is active with Auto-inject CMP Script enabled

confirm wp-consent-bridge.js loads before loader.js

remove duplicate/manual CMP embeds on the same page

if using custom mapping hooks, validate final category map

Symptoms:

banner appears, but Shopify consent categories do not change

currentVisitorConsent() stays unchanged after Accept/Reject

Root causes:

App Embed disabled

missing or invalid Settings ID

duplicate injection (App Embed + manual loader script)

stale storefront cache

How to confirm:

Fix:

enable NexaGuard CMP in Online Store -> Themes -> Customize -> App embeds

set a valid Settings ID and save theme customizer changes

keep only one injection path (prefer App Embed)

hard refresh storefront and retest in an incognito window

Troubleshooting Playbook

1. Banner Not Showing#

2. Tags Fire Before Consent Default#

3. Consent Not Updating After User Action#

4. Duplicate Banner#

5. TCF API Missing#

6. What to Send Support#

7. iOS Pod Version Not Found Right After Release#

8. Android SDK Version Not Found Right After Release#

9. Sonatype Close Fails: Component Already Exists#

10. WordPress: WP Consent Categories Not Updating#

11. Shopify: Customer Privacy Consent Not Updating#

1. Banner Not Showing

2. Tags Fire Before Consent Default

3. Consent Not Updating After User Action

4. Duplicate Banner

5. TCF API Missing

6. What to Send Support

7. iOS Pod Version Not Found Right After Release

8. Android SDK Version Not Found Right After Release

9. Sonatype Close Fails: Component Already Exists

10. WordPress: WP Consent Categories Not Updating

11. Shopify: Customer Privacy Consent Not Updating