Troubleshooting

"Provider not found" Error

Symptom: useConsentManager must be used within a ConsentManagerProvider error.

Fix: Ensure the component calling useConsentManager() (or any c15t hook) is rendered inside a ConsentManagerProvider:

// Wrong — hook is outside the provider
function App() {
  const { consents } = useConsentManager(); // throws
  return <ConsentManagerProvider options={...}>...</ConsentManagerProvider>;
}

// Correct — hook is inside the provider
function App() {
  return (
    <ConsentManagerProvider options={...}>
      <MyComponent /> {/* useConsentManager works here */}
    </ConsentManagerProvider>
  );
}

Banner Doesn't Show

Possible causes:

1. Opt-out jurisdiction — In CCPA/opt-out regions, the banner is not shown because tracking is allowed by default. Check model from useConsentManager() — if it's 'opt-out', the banner is intentionally hidden.

2. Consent already given — If the user has already made a consent choice, the banner won't reappear. Clear cookies or use resetConsents() to test again.

3. activeUI is 'none' — Something is explicitly setting activeUI to 'none'. Check the DevTools panel for the current consent state.

4. Backend not responding — In 'c15t' mode, the banner waits for the backend /init response. Check the Network tab for failed requests to your backendURL.

// Debug: check what the consent manager sees
const { activeUI, model, isLoadingConsentInfo } = useConsentManager();
console.log({ activeUI, model, isLoadingConsentInfo });

Consent Not Persisting

Symptom: Consent is lost after page reload.

Possible causes:

1. Incognito/private mode — Some browsers restrict cookie storage in private browsing.

2. Cookie settings — In 'offline' mode, consent is stored in cookies. Ensure cookies are not being blocked by browser settings or extensions.

3. Different domains — Cookies are domain-scoped. If your dev server uses a different domain than production, consent won't carry over.

4. Backend errors — In 'c15t' mode, check that the backend is saving consent successfully. Enable debug: true in provider options to see detailed logs.

Scripts Not Loading

Symptom: Third-party scripts configured in the scripts option don't load after consent is granted.

Checklist:

1. Wrong category name — The category on the script must match one of the consentCategories names. For example, 'measurement' not 'analytics'.

2. Consent condition not met — Use has('measurement') to verify the category is actually consented.

3. Script error — Check the browser DevTools Console for script loading errors. The onError callback can help debug:

{
  id: 'analytics',
  src: 'https://...',
  category: 'measurement',
  onError: ({ error }) => console.error('Script failed:', error),
}

4. Ad blocker — Browser extensions may block the script regardless of consent. The anonymizeId option (default: true) helps avoid pattern-based blocking.

Store Not Accessible

Symptom: window.c15tStore is undefined, or consentStore.getState() throws an error.

Fixes:

1. Runtime not initialized — Ensure getOrCreateConsentRuntime() has been called before accessing the store:

import { getOrCreateConsentRuntime } from 'c15t';

const { consentStore } = getOrCreateConsentRuntime({
  mode: 'c15t',
  backendURL: 'https://your-instance.c15t.dev',
});

// Now the store is accessible
console.log(consentStore.getState());
console.log(window.c15tStore?.getState());

2. Script load order — If using <script> tags, make sure the script that initializes the runtime loads before any scripts that access window.c15tStore.

3. Custom namespace — If you set a custom namespace in store options, the window property will use that name instead of c15tStore.

Still Stuck?

• Enable debug: true in runtime options for verbose console logging
• Inspect window.c15tStore?.getState() in the browser console
• Check the GitHub issues for known bugs