Microsoft Clarity Troubleshooting & Debugging | Blue Frog Docs

Microsoft Clarity Troubleshooting & Debugging

Solve common Microsoft Clarity implementation issues, fix tracking problems, and optimize performance

Microsoft Clarity Troubleshooting & Debugging

Overview

Microsoft Clarity is designed to be straightforward, but even simple tools can run into issues. This guide covers the most common problems users encounter, how to diagnose them, and step-by-step solutions to get Clarity working properly.

Whether you're seeing no data, missing sessions, or performance issues, this guide will help you troubleshoot and fix the problem.

Installation & Setup Issues

No Data Appearing in Dashboard

Symptoms:

  • Clarity project created, tracking code installed, but dashboard shows zero sessions
  • "Waiting for data" message persists for hours or days

Common Causes:

1. Tracking Code Not Installed Correctly

Check:

  • View page source on your website (right-click > View Page Source)
  • Search for "clarity.ms" or your Clarity Project ID
  • If the script doesn't appear, the code isn't installed

Fix:

<!-- Correct installation in <head> section -->
<!DOCTYPE html>
<html>
<head>
  <title>Your Site</title>
  <!-- Microsoft Clarity -->
  <script type="text/javascript">
    (function(c,l,a,r,i,t,y){
        c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
        t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;
        y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
    })(window, document, "clarity", "script", "YOUR_PROJECT_ID");
  </script>
</head>
<body>
  <!-- Your content -->
</body>
</html>

Verify Project ID:

  • In Clarity dashboard, go to Settings > Setup
  • Copy the full tracking code again
  • Replace the entire script, don't just change the ID

2. Ad Blockers or Browser Extensions Blocking Clarity

Check:

  • Disable browser extensions (uBlock Origin, Privacy Badger, Ghostery, etc.)
  • Visit your site in incognito/private mode
  • Check if sessions appear now

Fix:

  • You can't control user ad blockers, but you can verify Clarity works for users without them
  • Consider adding a note in your analytics documentation that ad blockers reduce data coverage
  • Typical ad blocker impact: 10-30% of sessions may be blocked

3. Content Security Policy (CSP) Blocking Script

Symptoms:

  • Browser console shows CSP violation errors
  • Script fails to load despite being in HTML

Check Console for Errors:

Refused to load the script 'https://www.clarity.ms/tag/...' because it violates
the following Content Security Policy directive: "script-src 'self'"

Fix: Update your CSP header to allow Clarity:

Content-Security-Policy: script-src 'self' https://www.clarity.ms;
                         connect-src 'self' https://www.clarity.ms;

Or in HTML meta tag:

<meta http-equiv="Content-Security-Policy"
      content="script-src 'self' https://www.clarity.ms; connect-src 'self' https://www.clarity.ms;">

4. Wrong Project ID

Check:

  • In Clarity dashboard: Settings > Overview > Project ID
  • In your website code: Search for clarity.ms/tag/ and check the ID after it
  • They must match exactly

Fix: Replace the Project ID in your tracking code with the correct one from the dashboard.

5. Cached Version of Site Without Tracking Code

Check:

  • Hard refresh your browser (Ctrl+Shift+R or Cmd+Shift+R)
  • Clear browser cache
  • Check page source to verify script is present

Fix:

  • Clear CDN cache if using Cloudflare, AWS CloudFront, etc.
  • Purge WordPress cache if using caching plugins (WP Super Cache, W3 Total Cache)
  • Wait for cache TTL to expire naturally

Data Delayed or Not Real-Time

Symptoms:

  • Sessions appear in dashboard hours after they occurred
  • Dashboard says "data processing" for extended periods

Expected Behavior:

  • Clarity processes data near real-time, but there can be 5-15 minute delays
  • During high traffic, delays may extend to 30-60 minutes
  • This is normal and doesn't indicate a problem

Not Normal:

  • Data delayed by several hours
  • Data from yesterday still processing

Fix:

  1. Check Clarity status page: https://clarityhealth.microsoft.com/
  2. If status shows issues, wait for Microsoft to resolve
  3. If status is green but you have delays, contact Clarity support with:
    • Project ID
    • Timestamp of affected sessions
    • Number of sessions impacted

Incomplete or Missing Recordings

Symptoms:

  • Some sessions have recordings, others don't
  • Recordings cut off mid-session
  • Heatmaps show data but no recordings available

Common Causes:

1. Session Sampling Enabled

If you implemented custom sampling (e.g., only tracking 50% of sessions), some recordings won't exist by design.

Check Your Code:

// If you have code like this, sampling is active
if (Math.random() < 0.5) {
  // Load Clarity
}

Fix: Remove sampling logic if you want full coverage.

2. User Left Page Too Quickly

Sessions under 3 seconds may not be recorded. This is expected behavior for bots and immediate bounces.

3. Recordings Disabled in Settings

Check:

  • In Clarity dashboard: Settings > Setup > Recording
  • Ensure "Enable session recordings" is turned ON

Fix: Toggle the setting to ON and save.

4. Browser Compatibility Issues

Clarity supports modern browsers but may have issues with:

  • Internet Explorer (deprecated, partial support)
  • Very old versions of Safari or Firefox

Check:

  • Look at browser breakdown in Clarity dashboard
  • Filter recordings by browser to see if specific browsers have no recordings

Fix:

  • Ensure users are on supported browsers (Chrome, Firefox, Edge, Safari last 2 versions)
  • Update Clarity tracking code to the latest version

Google Analytics Integration Issues

GA Data Not Showing in Clarity

Symptoms:

  • Clarity and GA are both working independently
  • No GA dimensions (Source, Medium, Campaign) appear in Clarity filters
  • Can't segment Clarity sessions by GA traffic sources

Common Causes:

1. Integration Not Connected

Check:

  • In Clarity: Settings > Integrations > Google Analytics
  • Status should show "Connected" with the correct GA4 property

Fix:

  1. Disconnect the integration
  2. Reconnect it, ensuring you:
    • Sign in with the correct Google account
    • Select the right GA4 property
    • Grant all requested permissions

2. Using Universal Analytics Instead of GA4

Clarity only integrates with GA4, not the deprecated Universal Analytics.

Check:

  • In Google Analytics, look at the Property ID
  • GA4 properties start with "G-" (e.g., G-XXXXXXXXXX)
  • Universal Analytics properties start with "UA-" (e.g., UA-XXXXXXXXXX)

Fix:

  • Set up GA4 if you haven't already
  • Link Clarity to the GA4 property, not Universal Analytics

3. Data Not Yet Available

Expected Delay:

  • Integration takes 24-48 hours to start populating data
  • Only new sessions after connection will have GA data
  • Historical sessions won't be backfilled

Fix: Wait 48 hours after connecting the integration, then check again.

4. GA4 Not Collecting Data

If GA4 itself isn't tracking, Clarity can't pull data from it.

Check:

  • Go to GA4 dashboard > Reports > Realtime
  • Verify sessions are being tracked in GA4
  • Ensure GA4 tracking code is installed on the same pages as Clarity

Fix: Fix GA4 tracking first, then the Clarity integration will automatically start receiving data.

Clarity Session URLs Not Appearing in GA4

Symptoms:

  • Clarity and GA are integrated
  • Can filter Clarity by GA data
  • But can't see Clarity session links in GA4 reports

Fix:

Create Custom Dimension in GA4

  1. In GA4: Admin > Custom Definitions > Custom Dimensions
  2. Click Create custom dimension
  3. Enter:
    • Dimension name: Clarity Session URL
    • Scope: Event
    • Event parameter: clarity_session_url
  4. Save

Build Exploration with Clarity URLs

  1. In GA4: Explore > Blank exploration
  2. Add dimensions: Page, Device, Source, and "Clarity Session URL"
  3. Add metrics: Sessions, Conversions
  4. Build a table showing Clarity URLs for each session segment

Now you can click Clarity URLs directly from GA4 explorations.

Performance Issues

Clarity Slowing Down Website

Symptoms:

  • Page load times increased after installing Clarity
  • Lighthouse/PageSpeed scores dropped
  • Users reporting slower site

Diagnosis:

1. Check If Clarity Is Actually the Cause

Use Browser DevTools:

  1. Open DevTools (F12)
  2. Go to Network tab
  3. Reload page
  4. Look for clarity.ms requests
  5. Check:
    • Time to load Clarity script (should be < 200ms)
    • Size of Clarity script (should be < 50KB)

Expected: Clarity adds ~50-100ms to page load. Not noticeable to users.

Problem: If Clarity script takes > 1 second or blocks other resources, something's wrong.

2. Script Not Loading Asynchronously

Check Your Code:

<!-- WRONG: Synchronous loading blocks page render -->
<script src="https://www.clarity.ms/tag/YOUR_ID"></script>

<!-- CORRECT: Async script from Clarity dashboard -->
<script type="text/javascript">
  (function(c,l,a,r,i,t,y){
    c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
    t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;
    y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
  })(window, document, "clarity", "script", "YOUR_PROJECT_ID");
</script>

Fix: Use the official async tracking code from Clarity dashboard, not a manual <script src> tag.

3. Too Many Recordings on High-Traffic Pages

If your site has extremely high traffic (millions of sessions/day), recording every session can create overhead.

Fix: Implement Sampling

// Only track 25% of sessions
if (Math.random() < 0.25) {
  (function(c,l,a,r,i,t,y){
    // Clarity tracking code
  })(window, document, "clarity", "script", "YOUR_PROJECT_ID");
}

Or use conditional loading:

// Only track on specific pages
if (window.location.pathname.includes('/checkout') ||
    window.location.pathname.includes('/product')) {
  // Load Clarity
}

4. Clarity Script Blocked, Causing Timeouts

If Clarity's CDN is unreachable (corporate firewall, region block), the script may timeout.

Check Console for Errors:

Failed to load resource: net::ERR_CONNECTION_TIMED_OUT
https://www.clarity.ms/tag/YOUR_ID

Fix:

  • Whitelist clarity.ms domain in firewall
  • If users are in regions where Microsoft services are blocked, consider not loading Clarity for those users

High Memory Usage from Recordings

Symptoms:

  • Browser tab using excessive memory
  • Browser becomes sluggish on pages with Clarity
  • Console warnings about memory

Cause: Clarity records DOM changes, which can consume memory on very complex or dynamic pages (single-page apps with thousands of DOM updates).

Fix:

Disable Clarity on Specific Heavy Pages

// Don't load Clarity on data-heavy dashboards
if (!window.location.pathname.includes('/dashboard')) {
  // Load Clarity
}

Reduce DOM Complexity

  • Minimize unnecessary DOM elements
  • Lazy load content that's below the fold
  • Remove unused HTML/CSS/JS

Upgrade Clarity Tracking Code

Microsoft occasionally releases optimizations. Ensure you're using the latest version:

  1. Go to Clarity dashboard > Settings > Setup
  2. Copy the latest tracking code
  3. Replace your existing code

Data Quality Issues

Recordings Show Broken Layout or Missing Content

Symptoms:

  • Session recordings don't match actual site appearance
  • CSS styles missing
  • Images not loading in recordings
  • Layout completely broken

Causes:

1. CSS Loaded from External Domains

If stylesheets are on a different domain and don't allow cross-origin access, Clarity can't capture them.

Check:

  • Look at your <link> tags
  • If CSS is hosted on a CDN, ensure CORS headers allow Clarity to access them

Fix: Add CORS headers to your CSS files:

Access-Control-Allow-Origin: *

Or for more security:

Access-Control-Allow-Origin: https://www.clarity.ms

2. Dynamically Loaded Content After Page Load

Single-page apps and dynamic content may not be fully captured if loaded after Clarity initializes.

Fix: Ensure Clarity loads after your app framework initializes (React, Vue, Angular).

3. Shadow DOM or iFrames

Clarity has limited support for Shadow DOM and iframes. Content inside these may not be recorded accurately.

Workaround: Minimize use of Shadow DOM/iframes for critical UX elements, or accept that those sections won't be fully visible in recordings.

Heatmaps Not Matching Actual Page Layout

Symptoms:

  • Heatmap clicks appear in wrong locations
  • Scroll depth percentages don't align with page sections

Causes:

1. Dynamic Layout Changes

If your page layout changes based on user actions (collapsible sections, tabs, dynamic content), heatmaps aggregate data across all states, which can look misaligned.

Fix:

  • Filter heatmaps by device type to reduce layout variance
  • Accept that dynamic pages will have less precise heatmaps
  • Use session recordings to see individual interactions in context

2. Viewport Size Variance

Heatmaps overlay data from different screen sizes (mobile, tablet, desktop) onto a single view. This can make clicks appear "off."

Fix: Filter heatmaps by device type:

  • Dashboard > Heatmaps > Select page > Filter by Mobile or Desktop

Sensitive Data Visible in Recordings

Symptoms:

  • Password fields visible in recordings
  • Credit card numbers shown
  • Personal information not masked

Immediate Action:

  1. Go to Clarity dashboard > Settings > Privacy
  2. Enable Strict masking mode
  3. Delete sessions containing sensitive data:
    • Find affected sessions in Recordings
    • Click the session
    • Click Delete session (top right)

Permanent Fix:

Ensure Masking Is Enabled

Clarity automatically masks <input type="password">, but custom inputs may not be recognized.

Add Manual Masking:

<!-- Mask specific elements with class -->
<input type="text" class="clarity-mask" placeholder="SSN">
<div class="clarity-mask">Sensitive user info</div>

Mask Entire Sections:

<div class="clarity-mask">
  <p>This entire section won't be visible in recordings</p>
  <input type="text" name="credit-card">
</div>

Review Privacy Settings

In Clarity dashboard:

  • Settings > Privacy
  • Enable:
    • Mask sensitive text
    • Mask all input fields
    • Mask all images (if images might contain PII)

Custom Event Issues

Custom Events Not Appearing in Filters

Symptoms:

  • Custom events triggered via clarity("event", "event_name")
  • Events fire in console without errors
  • But events don't appear as filter options in Clarity dashboard

Causes:

1. Events Not Fired Yet

Clarity only shows custom events in filter dropdowns after they've been fired at least once.

Fix: Trigger the event on your site, wait 15-30 minutes, then check Clarity dashboard again.

2. Event Name Typos or Inconsistencies

Check Your Code:

// Inconsistent naming won't group events together
clarity("event", "checkoutComplete");  // Somewhere in code
clarity("event", "checkout_complete"); // Somewhere else

Fix: Use consistent naming:

// Standardize on one naming convention
clarity("event", "checkout_complete");

3. Events Fired Before Clarity Loads

If your custom event fires immediately on page load, it might fire before Clarity initializes.

Fix: Wrap in a timeout or check for Clarity availability:

// Wait for Clarity to be available
function trackCustomEvent(eventName) {
  if (typeof clarity !== 'undefined') {
    clarity("event", eventName);
  } else {
    setTimeout(function() { trackCustomEvent(eventName); }, 100);
  }
}

Custom Tags/Sets Not Filtering Correctly

Symptoms:

  • clarity("set", "key", "value") called
  • Tags don't appear in session filters

Fix:

Ensure clarity("set") is called before the session ends:

// Set user type early in session
window.addEventListener('load', function() {
  if (userIsPremium) {
    clarity("set", "user_type", "premium");
  } else {
    clarity("set", "user_type", "free");
  }
});

Debugging Tools & Techniques

Check Clarity Script Loaded

Browser Console:

// Check if Clarity object exists
if (typeof clarity !== 'undefined') {
  console.log('Clarity is loaded');
} else {
  console.log('Clarity is NOT loaded');
}

Verify Project ID

Browser Console:

// Extract Project ID from page source
let scripts = document.querySelectorAll('script');
scripts.forEach(s => {
  if (s.innerHTML.includes('clarity.ms/tag/')) {
    console.log('Clarity Project ID:', s.innerHTML.match(/clarity.ms\/tag\/(.*?)"/)[1]);
  }
});

Test Custom Events in Console

// Fire test event manually
clarity("event", "test_event");

// Set test tag
clarity("set", "test_key", "test_value");

// Check console for errors

Use Network Tab to Monitor Clarity Requests

  1. Open DevTools > Network
  2. Filter by "clarity.ms"
  3. Reload page
  4. Look for:
    • Initial script load: https://www.clarity.ms/tag/YOUR_ID
    • Data collection requests: https://www.clarity.ms/collect

If no collect requests appear after user interactions, Clarity isn't tracking properly.

Check Clarity Health Status

Visit: https://clarityhealth.microsoft.com/

This shows any ongoing issues with Clarity's infrastructure.

Getting Help

If you've tried these troubleshooting steps and still have issues:

1. Clarity Documentation

2. Clarity Support

  • Email: clarity-support@microsoft.com
  • Include:
    • Project ID
    • URL where Clarity is installed
    • Description of the issue
    • Steps you've already tried
    • Screenshots or console errors

3. Community Forums

4. GitHub Issues (Unofficial)

Check if others have reported similar issues in community discussions.

Quick Troubleshooting Checklist

No data in dashboard:

  • ✅ Tracking code installed in <head>?
  • ✅ Correct Project ID in code?
  • ✅ Ad blockers disabled for testing?
  • ✅ CSP headers allow clarity.ms?
  • ✅ Waited at least 30 minutes for data to process?

Recordings broken or missing:

  • ✅ Recordings enabled in Settings?
  • ✅ CSS hosted with CORS headers?
  • ✅ Session lasted > 3 seconds?
  • ✅ Using supported browser?

GA integration not working:

  • ✅ Connected to GA4 (not Universal Analytics)?
  • ✅ Waited 48 hours after connecting?
  • ✅ GA4 collecting data successfully?

Performance issues:

  • ✅ Using async tracking code?
  • ✅ Script loading from clarity.ms CDN?
  • ✅ Considered sampling for high-traffic sites?

Sensitive data exposed:

  • ✅ Strict masking enabled?
  • ✅ Sensitive inputs have clarity-mask class?
  • ✅ Affected sessions deleted?

Additional Resources:

↑ Back to top
// SYS.FOOTER