Troubleshooting

Solutions to the most common issues with the CADENCE SDK, Visual Editor, and dashboard.

SDK issues

Variant always returns "control"

Cause: getVariant() was called before the SDK finished loading.

Fix: Always await cadence.ready() before calling getVariant():

// Wrong
const variant = cadence.getVariant('my-test') // SDK hasn't loaded yet

// Right
await cadence.ready()
const variant = cadence.getVariant('my-test')

Also check:

• The experiment exists in the dashboard and is running (not draft or archived)
• The experiment name matches exactly (case-sensitive)
• Your SDK key belongs to the right project

Events not showing up in the dashboard

Cause: Events are batched and sent every 5 seconds.

Fix: Wait 10 seconds, then refresh the dashboard.

If events still don't appear:

1. Open your browser's Network tab (DevTools > Network)
2. Look for POST requests to /api/sdk/[key]/events
3. If the request is failing, check the response for error details

Common causes:

• Wrong SDK key
• apiUrl doesn't point to the CADENCE server
• Network issues or ad blockers blocking the request

Same user gets different variants across sessions

Cause: The user ID changes between sessions.

By default, the SDK generates a random user ID and stores it in localStorage. If localStorage is cleared, incognito mode is used, or the user switches devices, they get a new identity.

Fix: Pass your own stable user ID:

const cadence = new CadenceClient({
  sdkKey: 'your_key',
  userId: currentUser.id, // Your app's user ID
})

SDK config fetch fails (network error)

Cause: The SDK can't reach the CADENCE API.

Check these in order:

1. Is the API reachable? Try opening /api/sdk/[your-key]/config directly in the browser
2. Is apiUrl correct? If you set it explicitly, make sure it includes the protocol (https://)
3. Is the SDK key valid? It should be a 64-character hex string
4. Are there CORS issues? If the SDK runs on a different origin than the API, check for CORS errors in the console

Flash of unstyled content with visual mutations

Cause: The page renders before the SDK applies visual mutations.

Fix: Call enableAntiFlicker() before ready() and getVariant():

cadence.enableAntiFlicker(2000) // Max 2 seconds hidden
await cadence.ready()
cadence.getVariant('my-visual-test')

If you're not using enableAntiFlicker(), the page content is visible immediately and mutations are applied after the SDK loads, causing a brief flash.

SDK key rejected (401 or 403)

Cause: Invalid, expired, or regenerated SDK key.

Fix:

1. Go to your project in the CADENCE dashboard
2. Check that the SDK key matches what's in your code
3. SDK keys are 64-character hex strings (e.g., a1b2c3d4...)
4. If you regenerated the key, the old one no longer works

Visual Editor issues

Cross-origin restrictions detected

Cause: Your site and the CADENCE dashboard are on different domains. This is a browser security feature.

Fix: Use one of these workarounds:

1. Manual selectors — Type CSS selectors in the sidebar input instead of clicking
2. Same-origin development — Run both your site and CADENCE on localhost:3000
3. DevTools inspection — Find selectors in a separate tab and paste them in

See the Visual Editor docs for details.

Element not found after saving mutation

Cause: The CSS selector no longer matches an element on the page.

This happens when:

• The site was redesigned
• A class name was changed
• Dynamic/hashed class names rotated between builds
• The element loads after the DOM is ready (lazy loading, SPA routing)

Fix:

1. Open the Visual Editor and verify the selector
2. Update it to match the current DOM
3. Prefer ID selectors (#signup-btn) for long-term stability

Mutations don't appear on the live site

Check these in order:

1. Is the experiment running? Mutations only apply when getVariant() returns the right variant
2. Is getVariant() being called? Add a console.log to verify
3. Is the user in the right variant? getVariant() might return 'control' for this user
4. Are mutations saved? Re-open the Visual Editor and verify mutations are listed
5. Is anti-flicker hiding the page? Check if document.documentElement.style.visibility is 'hidden'

Dashboard issues

Redirected to onboarding when accessing a workspace

Cause: Your user account isn't a member of the workspace.

Fix: Ask the workspace owner to add you as a member. Membership is managed through the workspace_members table in the database.

Results show 0 conversions

Cause: trackConversion() isn't being called, or events haven't been sent yet.

Check:

1. Verify trackConversion() is in your code at the right moment
2. Open the Network tab and look for event batch requests
3. Wait at least 10 seconds for events to batch and send
4. Check the Events page for raw event data

Statistical significance not reached

This is normal — significance requires enough data.

Rules of thumb:

• Need at least 100 conversions per variant (not just exposures)
• Need at least 7 days to account for day-of-week effects
• Small effects (<5% lift) need much larger sample sizes

If you don't reach significance after your planned duration, that's a valid result. The difference between variants is too small to detect reliably.

Environment issues

NEXT_PUBLIC_CADENCE_SDK_KEY is undefined

Cause: Missing the framework-specific environment variable prefix.

| Framework | Required prefix | Example | |-----------|----------------|---------| | Next.js | NEXT_PUBLIC_ | NEXT_PUBLIC_CADENCE_SDK_KEY=abc123 | | Vite | VITE_ | VITE_CADENCE_SDK_KEY=abc123 | | Create React App | REACT_APP_ | REACT_APP_CADENCE_SDK_KEY=abc123 |

Important: Restart your dev server after changing .env files. Environment variables are read at build time, not runtime.

Cannot find module '@cadence/sdk'

Cause: The package isn't installed.

Fix:

npm install @cadence/sdk

If using yarn or pnpm:

yarn add @cadence/sdk
pnpm add @cadence/sdk

Still stuck?

Contact us at hello@cadence.tools with:

• Your SDK key (this is safe to share — it's not your Supabase key)
• Browser console output (screenshots or copy-paste)
• Network tab screenshots showing failed requests
• Steps to reproduce the issue

We respond within 24 hours on business days.