Troubleshooting for Nuxt
Common CookieYes setup problems, like a banner that never shows or scripts loading before consent, and the one line to check for each.
Most problems here are a setup detail, and several show no error at all. Find what you see in the table; each row is one line to check.
Find your symptom
| What you see | Cause | Fix |
|---|---|---|
| The banner never appears | You already chose in this browser, or closed it in this page view | Delete the cookieyes-consent cookie and reload, see Reset and re-test |
| The banner never appears, no error anywhere | <CookieYesRoot /> is not in app/app.vue | See Installation → Common mistakes |
Failed to resolve component: CookieYesRoot in the console | @cookieyes/nuxt is missing from modules | Add it to modules in nuxt.config.ts |
| An integration or a callback never runs | It is under cookieyes in nuxt.config.ts, which becomes JSON runtime config and drops functions | Move it under cookieyes in app/app.config.ts, see Configuration |
| The preferences dialog is unstyled, the banner is fine | Only the inlined critical CSS applied: the full stylesheet did not load | Check the request to /cookieyes/styles.css, or your stylesHref, in the Network tab |
| Do Not Sell does nothing | <CookieOptOut /> is not rendered | <CookieYesRoot /> renders it only when regulation, region.strictest or a region.map value is "CCPA". In your own <CookieYesRoot> slot, render it yourself |
| Customise or your own "Cookie settings" link does nothing | <CookiePreferences /> is not rendered | Your own <CookieYesRoot> slot replaces the default components. Render it in the slot |
| A tracker loads when a switch is flipped, before Save | You read the live values | Use useConsentCategory() or committedCategories, see useConsent |
| A custom category is missing | Your categories list was rejected; the console says why | See Configuration → Consent categories |
| The banner is in English although you set a language | The language is not in i18n.messages | Import the catalogue, see Translations |
| The recall button is an unstyled circle | class replaced its default class | Add cy-widget to your class |
| The banner flashes and vanishes for returning visitors | The page's HTML is the same for every visitor: ssr: false, nuxt generate, or a route with swr, isr, cache or prerender route rules | Expected on those pages: the browser hides the banner after hydration. A server-rendered route reads the visitor's cookie and sends no banner |
| Your CSS rule does nothing | A theme value sets the same property inline, or your selector loses to the SDK's | See Custom CSS |
| Scoped CSS or CSS Modules never reach the banner | The components render into <body> | Use global CSS with data-cy-part selectors |
| Tracking continues after the visitor withdraws consent | A script that already ran cannot be unloaded | Render ReloadNotice |
| Every returning visitor is asked again | You changed a category id, or which one is required | Expected. See CookiePreferences |
| A checkbox in your own dialog turns on but never off | @change="toggle" passes the event | Use @change="toggle(($event.target as HTMLInputElement).checked)" |
| Focus jumps to the top of the page when a dialog closes | The dialog was opened through the runtime directly | Open it with useConsentActions().showPreferences() |
| The banner is not where you put it in your code | It moves to the top of <body> so keyboard users reach it first | Expected. See Accessibility |
Console messages
... in nuxt.config.ts holds a function, which runtime config drops because it is JSON. Move it under `cookieyes` in app.config.ts.
A development warning from the module, naming the option, such as cookieyes.onConsentUpdate. Move that option to app/app.config.ts.
[cookieyes] useConsent() could not find CookieYes. Add app.use(CookieYes, config) before mounting the app, and call composables inside setup() or app.runWithContext().
The module installs the plugin for you, so in a Nuxt app this means the composable ran outside a component's setup(), for example inside an event handler. Call it at the top of <script setup> and use what it returns.
[cookieyes] <CookieYesRoot /> needs the @cookieyes/nuxt module in modules.
<CookieYesRoot /> rendered without the module's plugin. Add @cookieyes/nuxt to modules in nuxt.config.ts.
[cookieyes] OptOut.* sub-components must be rendered inside <OptOut.Root>.
An OptOut.* piece sits outside OptOut.Root. Move it inside. Preferences.* pieces give the same message about <Preferences.Root>.
[cookieyes] `asChild` expects exactly one element child.
You passed text, a fragment or two elements to a piece with asChild. Pass exactly one element.
[cookieyes] Invalid categories config (...). Falling back to the default five
Your categories list broke a rule; the reason is in the brackets. The built-in five are shown until you fix it.
[cookieyes] `regulation` is set manually, so region detection is ignored.
You set both regulation and region. Keep one.
[cookieyes] no translations for language "..."; staying on "..."
You switched to a language that is not in i18n.messages and has no loadLanguage. Add the catalogue.
Reset and re-test
Make the banner come back. Delete the cookieyes-consent cookie in DevTools → Application → Cookies, or run this in the console and reload:
document.cookie = "cookieyes-consent=; max-age=0; path=/";Or call useConsentActions().reset() from a button you show only in development.
See the banner from any location. Set regulation: "GDPR" while developing instead of relying on region detection.
Check which version a page runs. In the console:
window.CookieYesSDK; // { version: "x.y.z" }The SDK sets this in the browser on every page where it starts, whether or not the banner shows, so public technology scanners can recognise the SDK. It holds the @cookieyes/core version and nothing else.
Trigger the reload notice. Accept the category, reload so the tool starts, then withdraw it. Rejecting on a first visit never shows it, because nothing was running.
Next steps
- Installation: the three-step setup, with its own common mistakes
- Configuration: every option of the
cookieyeskey