> ## Documentation Index
> Fetch the complete documentation index at: https://docs.permutive.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Common Errors
> Troubleshoot common issues with the Permutive JavaScript SDK
This guide covers common issues and their solutions when integrating the Permutive JavaScript SDK.
The [Permutive Chrome Extension](/sdks/web/javascript-sdk/troubleshooting/chrome-extension) provides a visual way to inspect event requests, schema errors, cohort membership, and ad targeting without using the browser developer console.
## 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**
```html theme={"dark"}
```
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:
```javascript theme={"dark"}
!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","",{});
```
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:
```javascript theme={"dark"}
permutive.consent({ opt_in: true, token: 'abc' });
```
**Symptoms:**
* No Pageview events
* Other events work but not pageviews
**Solutions:**
1. **Verify web addon is called**
```javascript theme={"dark"}
permutive.addon('web', {
page: { type: 'article' }
});
```
2. **Check consent timing**
If using consent, call `consent()` before `addon('web')`:
```javascript theme={"dark"}
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:
```javascript theme={"dark"}
// 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 `permutive.addon('web', {...})` on each route change:
```javascript theme={"dark"}
// On route change
router.onRouteChange(function() {
permutive.addon('web', { 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:
```javascript theme={"dark"}
{ 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**
```javascript theme={"dark"}
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**
```javascript theme={"dark"}
pbjs.setConfig({
realTimeData: {
auctionDelay: 200,
dataProviders: [{
name: 'permutive',
waitForIt: true // Critical!
}]
}
});
```
3. **Add TCF exception if needed**
```javascript theme={"dark"}
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**
```javascript theme={"dark"}
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 ``
**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.loggingEnabled=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:**
* Customer Success Manager
* [Technical Services](mailto:technical-services@permutive.com)
## Related Documentation
Visual deployment validation tool
Installation options
Verify integration
Consent handling
Understanding cohorts