Pendo Troubleshooting | Blue Frog Docs

Common Issues and Solutions

Pendo Agent Not Loading

Symptoms

No Pendo icon in bottom-right corner
Guides not appearing
Analytics data not collecting
pendo is undefined in console

Diagnostic Steps

1. Verify Installation

Check that the Pendo snippet is installed:

// Check in browser console
console.log(typeof pendo);
// Should output 'object' if loaded correctly

2. Confirm API Key

// Verify API key is set
console.log(pendo.apiKey);
// Should match your Pendo API key from settings

3. Check Initialization

// Verify visitor ID is set
console.log(pendo.getCurrentVisitor());
// Should return visitor object with ID

// Check account ID (if applicable)
console.log(pendo.getCurrentAccount());
// Should return account object with ID

4. Look for Console Errors

Common error messages:

pendo is not defined - Script not loaded
Visitor ID is required - Missing visitor.id in initialization
403 Forbidden - Invalid API key
CORS error - Cross-origin issues

Quick Fixes

// Force Pendo reload (for testing)
if (typeof pendo === 'undefined') {
  console.error('Pendo not loaded. Check script installation.');
} else {
  console.log('Pendo loaded successfully');
  console.log('Visitor ID:', pendo.getCurrentVisitor().id);
}

// Re-initialize Pendo (if needed)
pendo.initialize({
  visitor: {
    id: 'user-123',
    email: 'user@example.com'
  },
  account: {
    id: 'account-456'
  }
});

5. Verify Script Loading

<!-- Ensure script is in <head> -->
<script>
  (function(apiKey){
    (function(p,e,n,d,o){var v,w,x,y,z;o=p[d]=p[d]||{};o._q=o._q||[];
    // ... rest of Pendo snippet
  })("YOUR_API_KEY");
</script>

Guides Not Showing

Common Causes

1. Targeting Rules Not Met

User doesn't match segment criteria
Page URL doesn't match rules
Time-based rules not active
User already dismissed guide

Debugging Targeting:

// Check if user matches segment
pendo.getActiveGuides().forEach(guide => {
  console.log('Guide:', guide.name);
  console.log('Is eligible:', guide.isEligible);
  console.log('Segment conditions:', guide.segment);
});

// View all segments user belongs to
console.log('User segments:', pendo.getCurrentVisitor().segments);

2. Guide State Issues

Guide disabled or archived
Guide scheduled for future date
Maximum displays reached
Cooldown period active

Check Guide Status:

// List all guides and their status
pendo.guides.forEach(guide => {
  console.log(guide.name, {
    enabled: guide.enabled,
    state: guide.state,
    timesShown: guide.timesShown,
    maxShows: guide.maxShows
  });
});

3. Preview vs Production Mode

Test guides using preview mode:

// Enable preview mode
// Add ?pendo_preview=true to URL
// Or use Pendo Designer

// Force show specific guide (testing only)
pendo.showGuideById('GUIDE_ID');

4. Z-Index Issues

Guide may be hidden behind other elements:

/* Increase Pendo guide z-index if needed */
._pendo-guide-container_ {
  z-index: 999999 !important;
}

Solutions

Test Targeting Rules:

Open Pendo Designer
Preview guide on your site
Check "Why didn't this show?" in dashboard
Review segment membership
Verify page targeting rules

Reset Guide Display Count:

// Clear guide display history (testing only)
localStorage.removeItem('_pendo_visitorId._us.v');
location.reload();

Events Not Tracking

Troubleshooting Track Events

1. Verify Event Syntax

// Correct syntax
pendo.track('Event Name', {
  property: 'value'
});

// Check if event fired
console.log('Event tracked:', 'Event Name');

2. Check Event appears in Pendo

Navigate to Data > Events in Pendo dashboard
Filter by event name
Verify events appear within 5 minutes
Check event properties are correct

3. Debug Event Tracking

// Enable verbose logging
pendo.enableLogging();

// Track event with logging
pendo.track('Test Event', {
  test: true,
  timestamp: new Date().toISOString()
});

// Check network tab for POST to app.pendo.io

4. Common Mistakes

// Wrong - missing properties object
pendo.track('Event Name', 'property value');

// Wrong - not waiting for Pendo to load
pendo.track('Page Loaded');  // May fire before Pendo ready

// Correct - wait for Pendo
pendo.ready(function() {
  pendo.track('Page Loaded', { page: window.location.pathname });
});

Feature Tagging Issues

Features Not Being Tagged

1. Check Visual Designer Access

Click Pendo icon
Select "Designer"
Verify you can access Designer mode
Check if elements are selectable

2. Dynamic Content Problems

For dynamically loaded content:

// Wait for element to exist
function waitForElement(selector, callback) {
  const observer = new MutationObserver((mutations, me) => {
    const element = document.querySelector(selector);
    if (element) {
      me.disconnect();
      callback(element);
    }
  });
  observer.observe(document, {
    childList: true,
    subtree: true
  });
}

// Tag element after it loads
waitForElement('#dynamic-button', function(el) {
  // Element now exists and can be tagged in Designer
});

3. Single Page Application Issues

// Notify Pendo of route changes
window.addEventListener('popstate', function() {
  pendo.pageLoad();
});

// For React Router, Vue Router, etc.
// Call pendo.pageLoad() after route change

Data Sync Issues

Visitor/Account Data Not Updating

1. Update Metadata

// Update visitor properties
pendo.updateOptions({
  visitor: {
    id: 'user-123',
    role: 'admin',  // Updated property
    plan: 'enterprise'  // New property
  }
});

// Verify update
console.log(pendo.getCurrentVisitor());

2. Account-Level Data

// Update account properties
pendo.identify({
  visitor: {
    id: 'user-123'
  },
  account: {
    id: 'account-456',
    mrr: 999,  // Updated
    plan: 'enterprise',  // Updated
    employee_count: 150  // New
  }
});

3. Data Appears in Dashboard

Allow 5-15 minutes for data to appear
Check Settings > Visitor & Account Metadata
Verify field names match exactly
Check data types are correct (string, number, boolean)

Performance Issues

Slow Page Load

1. Optimize Script Loading

<!-- Use async loading -->
<script async>
  (function(apiKey){
    // Pendo snippet
  })("YOUR_API_KEY");
</script>

2. Reduce Agent Size

Remove unused integrations
Disable features not in use
Use lazy loading for guides

3. Limit Auto-Capture

pendo.initialize({
  apiKey: 'YOUR_API_KEY',
  visitor: { id: 'user-123' },

  // Reduce auto-capture frequency
  disableAutoCapture: false,
  excludeElements: ['.no-track']
});

Privacy and Compliance

PII in Session Replay

1. Mask Sensitive Data

// Configure PII masking
pendo.initialize({
  apiKey: 'YOUR_API_KEY',
  visitor: { id: 'user-123' },

  // Add selectors to mask
  excludeAllText: false,
  excludeElement: [
    '#password',
    '.credit-card',
    '[data-sensitive]'
  ]
});

2. Disable Session Replay

pendo.initialize({
  apiKey: 'YOUR_API_KEY',
  visitor: { id: 'user-123' },
  disableSessionRecording: true
});

3. Exclude Specific Pages

// Don't load Pendo on sensitive pages
if (window.location.pathname.includes('/admin/')) {
  console.log('Pendo disabled on admin pages');
} else {
  // Initialize Pendo
  pendo.initialize(/* ... */);
}

Debugging Tools

Enable Debug Mode

// Enable verbose logging
pendo.enableLogging();

// View all Pendo data
console.log('Current visitor:', pendo.getCurrentVisitor());
console.log('Current account:', pendo.getCurrentAccount());
console.log('Active guides:', pendo.getActiveGuides());
console.log('Metadata:', pendo.getMetadata());

Test in Staging

Use separate API key for staging
Test guides before publishing
Verify targeting rules
Check data collection

Browser Console Diagnostics

// Comprehensive Pendo diagnostic
console.log('=== Pendo Diagnostics ===');
console.log('Loaded:', typeof pendo === 'object');
console.log('API Key:', pendo.apiKey);
console.log('Visitor ID:', pendo.getCurrentVisitor().id);
console.log('Account ID:', pendo.getCurrentAccount()?.id);
console.log('Active Guides:', pendo.getActiveGuides().length);
console.log('Features Tagged:', Object.keys(pendo.getFeatures()).length);

Getting Additional Help

Support Resources

Support Portal: support.pendo.io
Email Support: support@pendo.io
Community: community.pendo.io
Documentation: developers.pendo.io
Status Page: status.pendo.io
Academy: Pendo Academy for training

Before Contacting Support

Prepare this information:

Pendo API key
Affected user/visitor IDs
Guide IDs (if guide-related)
Browser and version
Console errors (screenshots)
Steps to reproduce
When issue started
Recent changes to implementation

Escalation Path

Check documentation and community
Submit support ticket with details
Schedule call with support engineer (paid plans)
Escalate to customer success manager (enterprise)

Related Resources: