Skip to main content
This guide covers common issues and their solutions when integrating the Permutive JavaScript SDK.

Installation

Tracking

Targeting

​
Installation Issues

Symptoms:
  • window.permutive is undefined
  • No console messages with debug mode
  • Network tab shows 404 for live.js
Solutions:
  1. Verify script URL 
    <!-- Correct URL format -->
<script async src="https://<ORGANIZATION_ID>.edge.permutive.app/<WORKSPACE_ID>-web.js"></script>
  2. Check for Content Security Policy (CSP) issues 
    Content-Security-Policy: script-src 'self' https://*.permutive.app;
connect-src 'self' https://*.permutive.com https://*.permutive.app;
  3. Ensure loader script runs first The inline loader script must execute before the SDK script loads.
  4. Check for JavaScript errors Earlier errors may prevent subsequent scripts from running.
Symptoms:
  • Syntax errors in console
  • permutive is not defined errors
Solutions:
  1. Verify loader script is complete Ensure the entire loader script is copied correctly: 
    !function(e,o,n,i){if(!e){e=e||{},window.permutive=e,e.q=[];var t=function(){return([1e7]+-1e3+-4e3+-8e3+-1e11).replace(/[018]/g,function(e){return(e^(window.crypto||window.msCrypto).getRandomValues(new Uint8Array(1))[0]&15>>e/4).toString(16)})};e.config=i||{},e.config.apiKey=o,e.config.workspaceId=n,e.config.environment=e.config.environment||"production",(window.crypto||window.msCrypto)&&(e.config.viewId=t());for(var g=["addon","identify","track","trigger","query","segment","segments","ready","on","once","user","consent"],r=0;r<g.length;r++){var w=g[r];e[w]=function(o){return function(){var n=Array.prototype.slice.call(arguments,0);e.q.push({functionName:o,arguments:n})}}(w)}}}(window.permutive,"<WORKSPACE_API_KEY>","<WORKSPACE_ID>",{});
  2. Check for quote issues Template engines may escape quotes incorrectly.
  3. Verify API key and workspace ID Ensure credentials don’t contain special characters that need escaping.
Symptoms:
  • Console error: “Refused to load the script…”
  • Console error: “Blocked by Content Security Policy”
Solution: Add Permutive domains to your Content Security Policy:
Content-Security-Policy:
  script-src 'self' https://*.permutive.app;
  connect-src 'self' https://*.permutive.com https://*.permutive.app;
  img-src 'self' https://*.permutive.com;
Symptoms:
  • SDK loads on some browsers but not others
  • Network requests blocked
Solutions:
  1. Most ad blockers do not block Permutive as it’s a first-party tool
  2. If blocked, users will still see the site but without personalization
  3. Test with ad blockers disabled to confirm this is the cause

​
Tracking Issues

Symptoms:
  • track() called successfully
  • Debug mode shows “Event accepted”
  • Nothing in Permutive dashboard
Solutions:
  1. Wait for processing Events may take a few minutes to appear in the dashboard.
  2. Check date/time filters Ensure dashboard filters include the current time period.
  3. Verify workspace Confirm you’re viewing the correct workspace in the dashboard.
  4. Check consent status If consentRequired: true, ensure consent was granted: 
    permutive.consent({ opt_in: true, token: 'abc' });
Symptoms:
  • No Pageview events
  • Other events work but not pageviews
Solutions:
  1. Verify web addon is called 
    permutive.addon('web', {
  page: { type: 'article' }
});
  2. Check consent timing If using consent, call consent() before addon('web'): 
    permutive.consent({ opt_in: true, token: 'abc' });
permutive.addon('web', { page: { type: 'article' } });
  3. Check for duplicate calls Ensure addon('web') isn’t called multiple times.
Symptoms:
  • consentRequired: true configured
  • Events called but not tracked
  • No errors in console
Cause: Events called before consent({ opt_in: true }) are discarded (not queued).Solution: Always call consent() before tracking:
// 1. Grant consent first
permutive.consent({ opt_in: true, token: 'abc' });

// 2. Then initialize tracking
permutive.addon('web', { page: { type: 'article' } });
Symptoms:
  • First pageview tracks
  • Subsequent route changes don’t track
Solution: Call reset() on route changes:
var webAddon = permutive.addon('web', { page: getPageProps() });

// On route change
router.onRouteChange(function() {
  webAddon.reset({ page: getPageProps() });
});
Symptoms:
  • Different user ID on each visit
  • User history not persisting
Causes:
  • Cookies being blocked or cleared
  • Private browsing mode
  • Cookie domain mismatch
Solutions:
  1. Check cookie exists Look for permutive-id in Application > Cookies
  2. Verify cookie domain Ensure domain matches your configuration: 
    { cookieDomain: '.example.com' }
  3. Check browser settings Some browsers aggressively clear first-party cookies.

​
Targeting Issues

Symptoms:
  • permutive.segments() returns []
  • localStorage keys empty
Solutions:
  1. Wait for realtime data 
    permutive.ready(function() {
  permutive.segments(function(segs) {
    console.log(segs);  // Now populated
  });
}, 'realtime');
  2. Verify cohorts exist Check that cohorts are configured in dashboard.
  3. Confirm user qualifies User must meet cohort criteria to be included.
  4. Check consent Cohorts require consent to be tracked and calculated.
  5. Allow processing time New cohort membership may take a few seconds.
Symptoms:
  • Segments exist in localStorage
  • Targeting set on GPT
  • Line items not matching
Solutions:
  1. Verify key name Ensure GAM key is exactly permutive (case-sensitive).
  2. Check value format Values should be strings, not numbers.
  3. Verify targeting in Google Publisher Console Add ?googfc to URL and check targeting values.
  4. Confirm line item targeting Double-check line item uses correct key-value targeting.
Symptoms:
  • RTD module configured
  • Bid requests missing Permutive data
Solutions:
  1. Verify RTD module included Check Prebid build includes permutiveRtdProvider.
  2. Check configuration 
    pbjs.setConfig({
  realTimeData: {
    auctionDelay: 200,
    dataProviders: [{
      name: 'permutive',
      waitForIt: true  // Critical!
    }]
  }
});
  3. Add TCF exception if needed 
    vendorExceptions: ['permutive']
  4. Check localStorage Verify segment data exists in _pdfps, _papns, etc.
Symptoms:
  • User should qualify for new cohorts
  • Segments remain unchanged
Solutions:
  1. Verify events are tracking Check dashboard for incoming events.
  2. Check cohort rules Ensure user behavior matches cohort criteria.
  3. Allow processing time Cohort updates may take a few seconds to minutes.
  4. Refresh page Page reload triggers re-evaluation.
  5. Use triggers for real-time 
    permutive.trigger(12345, 'segment', function(inCohort) {
  console.log('Cohort status:', inCohort);
});

​
Console Errors

Cause: SDK not loaded when method called.Solutions:
  1. Ensure loader script runs before any permutive.* calls
  2. Check for script loading errors
  3. Verify script placement in <head>
Causes:
  • Network connectivity issues
  • API endpoint unreachable
  • Request blocked
Solutions:
  1. Check network connectivity
  2. Verify no proxy/firewall blocking
  3. Check CSP configuration
  4. Enable debug mode for details
Cause: Missing or incorrect API key/workspace ID.Solutions:
  1. Verify API key from dashboard
  2. Verify workspace ID from dashboard
  3. Check for extra whitespace or newlines
  4. Ensure credentials match environment (production vs staging)

​
Debug Mode

Enable debug mode to diagnose issues: 
https://yoursite.com/page?permutive_debug=true
Debug output includes:
  • SDK initialization status
  • Event tracking confirmations
  • Segment calculations
  • API request/response details
  • Error messages

​
Getting More Help

If you can’t resolve the issue:
  1. Gather diagnostic information:
    • Debug mode console output
    • Network tab screenshots
    • localStorage contents
    • Browser and version
  2. Contact support:

Installation

Installation options

Verification

Verify integration

Consent

Consent handling

Cohorts

Understanding cohorts