> ## Documentation Index > Fetch the complete documentation index at: https://docs.userpilot.com/llms.txt > Use this file to discover all available pages before exploring further. # Userpilot Error Reference > Common Userpilot errors with symptoms, causes, and solutions for SDK issues, API errors, content problems, and targeting failures. # 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 `` section * Check browser console for CSP errors * Add `js.userpilot.io` to CSP `script-src` directive * Consider [custom domain hosting](/developer/custom-domain) 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**: ```javascript theme={null} // 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**: ```javascript theme={null} // 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](/configure/exclude-lists/dynamic-attributes) 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](/api-references/import/overview) ### 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