Troubleshooting

Comprehensive troubleshooting guide for ClickBeam, SkyBeam, and platform integrations. Find solutions to common issues, debug tracking problems, and optimize your implementation.

Troubleshooting
Debugging

Quick Navigation

→ Installation Issues → Event Tracking Issues → Platform Integration Issues → Coordination Issues → Performance Issues → Debugging Tools

Installation Issues

Script Not Loading (404 Error)

Symptoms:

  • Network tab shows 404 for /magic/advertiser-id.min.js
  • Console shows "Failed to load resource" error
  • No ClickBeam initialization messages appear

Solutions:

  1. Verify Script URL: Check installation script in advertiser dashboard matches deployed script URL
  2. Check ClickBeam Deployment: Navigate to advertiser dashboard and verify "ClickBeam Deployed" status shows green checkmark
  3. Redeploy if Needed: Click "Deploy" button and run deployment process again
  4. Verify Domain Configuration: If using custom domains, check CNAME records point to correct targets

CORS (Cross-Origin Resource Sharing) Errors

Symptoms:

  • Console shows "CORS policy" errors
  • Network requests blocked or show "Preflight" failures
  • Events tracked but responses blocked

Solutions:

  1. Set Up CNAME: Configure DNS CNAME record (e.g., beam.yourdomain.com) pointing to API domain
  2. Update Installation Script: Modify script to use your CNAME domain instead of direct API domain
  3. Configure Advertiser Settings: Update api_domain setting in advertiser configuration to match CNAME
  4. Test First-Party Context: Verify API calls now originate from same domain as website

"beam is not defined" Error

Symptoms:

  • Console error: "ReferenceError: beam is not defined"
  • Events not tracked when using beam.method() pattern
  • Script loads but function calls fail

Solutions:

  1. Use Queue-Safe Pattern: Change beam.trackEvent() to beam('trackEvent', params)
  2. Verify Script Position: Ensure installation script is in <head> before any event tracking calls
  3. Check Async Loading: Script loads asynchronously - queue-safe pattern handles timing automatically
  4. Wait for Ready: If using direct pattern, wrap in window.addEventListener('load', ...)

Ad Blocker Interference

Symptoms:

  • Script loads in normal browser but fails with ad blockers enabled
  • Network requests blocked or show "canceled" status
  • Events track inconsistently across different users

Solutions:

  1. Implement CNAME: First-party context significantly reduces ad blocker interference
  2. Use Custom Subdomains: Host scripts on your own subdomain (e.g., tracking.yourdomain.com)
  3. Educate Users: Some tracking loss is expected with privacy tools - this is normal
  4. Monitor Impact: Track success rate to understand ad blocker impact on your audience

Event Tracking Issues

Events Not Firing

Symptoms:

  • Expected events don't appear in console or Network tab
  • User actions don't trigger tracking calls
  • Intelligence dashboard shows no events

Solutions:

  1. Check Event Binding: Verify event tracking code is attached to correct DOM elements/actions
  2. Inspect Console: Look for JavaScript errors preventing event code execution
  3. Test Manually: Run event call directly in console: beam('trackPurchase', {...})
  4. Verify Timing: Ensure tracking code runs after ClickBeam initialization
  5. Check Form Prevention: For form events, verify preventDefault() isn't blocking submission before tracking

Events Fire But Not Captured in Dashboard

Symptoms:

  • Network tab shows POST to /api/track
  • Response shows errors (400, 401, 500)
  • Events don't appear in Intelligence dashboard

Solutions:

  1. Check Response Status: Inspect Network response for specific error message
  2. 401 Unauthorized: Verify API token is active and correctly included in Authorization header
  3. 400 Bad Request: Review request payload for validation errors (missing required fields, unhashed PII)
  4. 500 Server Error: Contact support with trace ID from response headers for investigation
  5. Verify Advertiser ID: Ensure correct advertiser ID is configured in initialization

Duplicate Events

Symptoms:

  • Same event appears multiple times in Intelligence dashboard
  • Conversion metrics inflated
  • Platform reports show duplicate conversions

Solutions:

  1. Use Unique Event IDs: Generate unique event_id for each event (e.g., order ID, UUID)
  2. Avoid Multiple Script Instances: Check for duplicate installation scripts in page source
  3. Debounce Event Calls: Prevent rapid-fire duplicate calls from user interactions
  4. Check SPA Navigation: Single-page apps may re-fire events on route changes - implement navigation guards
  5. Verify Form Submission: Ensure form submit handler only fires once (not on both click and submit events)

Missing or Incomplete Event Data

Symptoms:

  • Events captured but missing expected fields
  • Platform forwarding fails due to missing required data
  • Conversion values missing or incorrect

Solutions:

  1. Inspect Network Payload: Check exact data being sent in POST request body
  2. Verify Field Names: Ensure field names match expected schema (e.g., value not price)
  3. Check Data Types: Numeric fields (value, quantity) must be numbers not strings
  4. Validate Currency Codes: Use ISO 4217 codes (USD, EUR, GBP) not symbols ($, €, £)
  5. Required vs Optional: Review API documentation for required fields per event type

Platform Integration Issues

Events Not Forwarding to Platforms

Symptoms:

  • Events appear in Intelligence dashboard but not in platform reports
  • Queue shows events stuck or failing
  • Platform event logs empty or show errors

Solutions:

  1. Verify Event Settings: Check Event Settings exist for the event type you're tracking
  2. Check Platform Configuration: Ensure platform is active with valid credentials in Connected Platforms
  3. Review Conversion Config: For Meta/LinkedIn, verify conversion config (pixel ID, conversion rule URN) is configured
  4. Inspect Queue Jobs: Navigate to Queue Management to see failed jobs and error messages
  5. Test Platform Connection: Use "Test Connection" button in platform settings to verify API access

Platform API Errors

Symptoms:

  • Platform event logs show 400/401/403/500 errors
  • Queue jobs repeatedly fail for platform delivery
  • Platform dashboards show no conversions

Solutions:

  1. Check API Credentials: Verify access tokens haven't expired or been revoked in platform
  2. Review Error Messages: Platform event logs show specific API error messages - address root cause
  3. Validate Permissions: Ensure API tokens have required permissions (ads_management, conversions, etc.)
  4. Check Platform Limits: Some platforms limit pixel/dataset access - verify configuration allows API access
  5. Re-authenticate: Try disconnecting and reconnecting platform to refresh credentials

Missing Conversion Configuration

Symptoms:

  • Queue filtering skips events for Meta or LinkedIn
  • Error logs mention "conversion config required"
  • Events tracked but not queued for platform delivery

Solutions:

  1. Configure Meta Pixel ID: In Event Settings, add Meta Pixel ID for conversion tracking
  2. Configure LinkedIn Conversion URN: Add LinkedIn conversion rule URN to Event Settings
  3. Verify Field Names: Check platform uses enable_conversions or enabled field
  4. Review Queue Logs: Check detailed queue filtering logs for specific missing fields
  5. Test Configuration: Use platform test tools to verify conversion config is detected

Event Processing Disabled

Symptoms:

  • Events queue but don't process to platforms
  • Queue jobs released back with delay
  • Red warning banner appears on Platforms page

Solutions:

  1. Check Global Processing: Navigate to Platforms page, verify global processing toggle is enabled
  2. Check Advertiser Processing: Verify advertiser-level processing isn't paused in settings
  3. Check Platform-Specific: Individual platform processing can be paused - check Connected Platforms
  4. Review Audit Trail: Check who disabled processing and when for troubleshooting context
  5. Re-enable Processing: Toggle processing back on - queued events will process after 5-minute delay

Coordination Issues (SkyBeam + ClickBeam)

Wrong Source Attribution

Symptoms:

  • Events show only "clickbeam" when expecting dual sources
  • Events show "unknown" source instead of "clickbeam" or "skybeam"
  • Inconsistent source attribution across similar events

Solutions:

  1. Verify Both Deployed: Check both SkyBeam and ClickBeam show deployed status in advertiser dashboard
  2. Test SkyBeam: Visit website, check Network tab for SkyBeam worker interception
  3. Check Coordination Cookies: Inspect Application tab → Cookies for beam_coordination
  4. Review Session IDs: Verify all events share same laser_beam_session ID
  5. Redeploy Both Systems: If coordination broken, redeploy both SkyBeam and ClickBeam together

Session ID Mismatch

Symptoms:

  • Events in same journey have different session IDs
  • Attribution dashboard shows fragmented journeys
  • Platform click IDs not persisting across pages

Solutions:

  1. Check Cookie Settings: Verify cookies aren't blocked by browser or privacy settings
  2. Verify Domain Consistency: Ensure tracking occurs on same root domain (not subdomain switching)
  3. Review Platform-Based Coordination: For platform traffic, coordination uses click IDs for deterministic sessions
  4. Check Cookie Expiration: Session cookies have 24-hour TTL - verify within timeframe
  5. Inspect LaserBeamSession: Check database for session creation and click ID capture

Missing Coordination Metadata

Symptoms:

  • Events missing tandem_tracking data
  • Source attribution shows null or empty array
  • Attribution reports can't determine event origin

Solutions:

  1. Verify Build Process: Ensure both systems rebuilt from shared modules (beam:prepare-js)
  2. Check Module Loading: Verify coordination.js module loads in both systems
  3. Review Event Structure: Check Events table for tandem_tracking JSON column
  4. Test Coordination Flow: Fire test event and inspect database record for tracking metadata
  5. Rebuild & Redeploy: Run full build sequence for both systems and redeploy

Performance Issues

Slow Script Loading

Symptoms:

  • Network tab shows long load time for tracking script
  • PageSpeed Insights shows tracking as render-blocking
  • Initial page load delayed by tracking setup

Solutions:

  1. Verify Async Loading: Ensure installation script uses j.async=true for non-blocking
  2. Set Up CNAME with CDN: Use first-party domain with CDN caching for faster delivery
  3. Check Server Response: Verify CDN/origin server responds quickly (< 200ms)
  4. Review Script Size: ClickBeam ~107KB minified - ensure no bundle bloat
  5. Enable HTTP/2: Verify server supports HTTP/2 for multiplexing

API Timeout Errors

Symptoms:

  • Network requests to /api/track timeout
  • Console shows "Request failed" or timeout errors
  • Events retry multiple times before failing

Solutions:

  1. Check Network Connectivity: Verify stable internet connection to API endpoint
  2. Review Payload Size: Large payloads (>100KB) may timeout - reduce data volume
  3. Implement Client Timeout: Set reasonable timeout (10-30s) with retry logic
  4. Use Batch API: For bulk operations, batch events to reduce request count
  5. Contact Support: If persistent, may indicate API infrastructure issue

Queue Processing Backup

Symptoms:

  • Queue Management shows thousands of pending jobs
  • Events delayed hours before processing
  • Platform delivery significantly lagged

Solutions:

  1. Check Queue Workers: Verify queue workers are running (queue:work process)
  2. Review Failed Jobs: Large number of failed jobs can slow queue - clear and retry
  3. Identify Bottleneck: Check which platform/event type is causing backup
  4. Temporary Pause: Pause problematic platform processing to clear queue
  5. Scale Workers: Contact support to increase queue worker capacity

Debugging Tools & Techniques

Browser Developer Tools

Console Tab

Check for JavaScript errors, initialization messages, and event tracking confirmations

Network Tab

Inspect API requests, response codes, payloads, and timing information

Application Tab

Review cookies, local storage, and session data for tracking state

Sources Tab

Set breakpoints in tracking code to debug event flow step-by-step

Platform Debugging Features

Intelligence Reports

Filter and search events, inspect complete event data, verify source attribution

Trace Logging

Track request flow through entire pipeline, identify bottlenecks and failures

Queue Management

Monitor job status, view failed jobs with error messages, retry failed deliveries

Platform Test Tools

Test platform connections, fire test events, validate API credentials

Advanced Debugging Commands

Check ClickBeam Initialization

// Run in browser console
console.log(typeof beam); // Should return "function"
console.log(beam.q); // Shows queued events before init

Test Event Manually

// Fire test event from console
beam('trackPageView', {
    event_id: 'debug-test-001',
    test_mode: true
});

Inspect Event Data Structure

// View last sent event in Network tab
// Click on /api/track request → Preview tab
// Review complete payload structure

Still Need Help?

If you've tried these troubleshooting steps and still experiencing issues, we're here to help.

Testing Guide → API Reference

Contact Support: Include trace IDs, advertiser ID, and specific error messages for faster resolution. Screenshots of browser console and Network tab are also helpful.