Skip to main content

​
Userpilot Error Reference

This reference covers common issues, their causes, and solutions.

​
SDK Issues

​
Userpilot not loading

Symptom: userpilot is undefined, content never appears Possible Causes:
  1. SDK script not included in page
  2. Script blocked by Content Security Policy (CSP)
  3. Script blocked by ad blocker
  4. Network error loading script
Solutions:
  • Verify script is in <head> section
  • Check browser console for CSP errors
  • Add js.userpilot.io to CSP script-src directive
  • Consider custom domain hosting for ad blocker issues
  • Verify network connectivity to js.userpilot.io

​
Content not displaying

Symptom: SDK loads but flows/tooltips don’t appear Possible Causes:
  1. identify() not called
  2. User doesn’t match targeting criteria
  3. User already seen content (frequency = once)
  4. Content not published
  5. Wrong environment (staging vs production)
Solutions:
  • Verify userpilot.identify() is called with valid user_id
  • Check targeting rules match current user/page
  • Test with a new user or reset seen content
  • Verify content is published, not draft
  • Confirm App Token matches environment

​
identify() not working

Symptom: User properties not updating, company not associated Possible Causes:
  1. Called before SDK loads
  2. Missing required user_id
  3. Invalid property format
  4. Company object missing id
Solutions: 
// Correct: wait for SDK
window.userpilot && userpilot.identify("user_123", {...});

// Correct: user_id is required
userpilot.identify("user_123", { name: "Jane" });

// Correct: company needs id
userpilot.identify("user_123", {
  company: { id: "company_456", name: "Acme" }
});

​
SPA navigation issues

Symptom: Content works on first page but not after navigation Cause: reload() not called on route changes Solution: 
// React Router
useEffect(() => {
  userpilot.reload();
}, [location]);

// Vue Router
router.afterEach(() => {
  userpilot.reload();
});

// Angular
router.events.pipe(
  filter(e => e instanceof NavigationEnd)
).subscribe(() => userpilot.reload());

​
API Errors

​
401 Unauthorized

Cause: Invalid or missing API key Solution:
  • Verify Authorization: Token {API_KEY} header
  • Check API key matches environment (production vs staging)
  • Regenerate API key if compromised

​
400 Bad Request

Cause: Invalid request body Common Issues:
  • Missing required fields (user_id for identify)
  • Invalid JSON syntax
  • Wrong data types (string instead of number)
  • Invalid date format (use ISO8601)

​
429 Too Many Requests

Cause: Rate limit exceeded Solution:
  • Implement exponential backoff
  • Batch requests where possible
  • Use bulk endpoints for high-volume operations

​
422 Validation Error

Cause: Data validation failed Common Issues:
  • Property name too long (max 255 chars)
  • Property value too large (max 65KB)
  • Invalid characters in property names
  • Duplicate user_id in bulk request

​
Content Issues

​
Element not found

Symptom: Tooltip/spotlight shows “element not found” or nothing appears Causes:
  1. Element selector changed (dynamic IDs/classes)
  2. Element not present on page
  3. Element inside iframe
  4. Element rendered after SDK evaluation
Solutions:
  • Use stable selectors (data attributes, semantic classes)
  • Add elements to exclude list for dynamic attributes
  • Userpilot cannot target iframe content
  • Use trigger delay or event-based triggers

​
Flow appears in wrong place

Symptom: Modal/tooltip positioned incorrectly Causes:
  1. Target element position changed
  2. CSS transforms affecting positioning
  3. Viewport/responsive layout issues
Solutions:
  • Re-select element in Chrome Extension
  • Test on target viewport size
  • Use modal instead of tooltip for complex layouts

​
Flow stuck / won’t advance

Symptom: User completes step but flow doesn’t continue Causes:
  1. Driven action element not clickable
  2. Page navigation before completion
  3. Element removed from DOM after click
Solutions:
  • Verify driven action element is interactive
  • Use page change handling in flow settings
  • Add delay or use different trigger method

​
Targeting Issues

​
Segment not matching users

Symptom: Users who should match don’t appear in segment Causes:
  1. Property not sent via identify()
  2. Property name mismatch (case-sensitive)
  3. Data type mismatch (string “100” vs number 100)
  4. Segment uses AND logic requiring all conditions
Solutions:
  • Verify property in user profile
  • Check exact property name spelling
  • Ensure consistent data types
  • Review segment logic (AND vs OR)

​
Content showing to wrong users

Symptom: Users outside target segment see content Causes:
  1. Segment criteria too broad
  2. User properties changed after initial match
  3. “Show once” not working due to reset
Solutions:
  • Add more specific targeting criteria
  • Use real-time property checks
  • Verify frequency settings

​
Data Issues

​
Events not appearing

Symptom: track() called but events don’t show in dashboard Causes:
  1. User not identified first
  2. Event name contains invalid characters
  3. Data processing delay (up to 15 minutes)
  4. Auto-capture disabled
Solutions:
  • Always call identify() before track()
  • Use alphanumeric event names with underscores
  • Wait for processing (check raw events first)
  • Enable auto-capture in settings if needed

​
Historical data missing

Symptom: User/company created but no historical data Cause: Userpilot only records data from first identify onwards Solution: Import historical data via Bulk Import API

​
Data discrepancy between Userpilot and other tools

Symptom: User counts differ from analytics tool Causes:
  1. Different user identification methods
  2. Bot/crawler traffic handled differently
  3. Sampling differences
  4. Timezone differences in date ranges
Solutions:
  • Compare identification logic
  • Exclude test/bot traffic consistently
  • Align date ranges and timezones
  • Accept minor variance as normal