Plausible Troubleshooting & Debugging | OpsBlu Docs

Plausible Troubleshooting & Debugging

Diagnose and fix common Plausible Analytics tracking issues. Covers script loading failures, missing events, data discrepancies, integration conflicts.

Overview

This guide helps you diagnose and resolve common Plausible Analytics tracking issues. Plausible is a lightweight, privacy-focused analytics platform that requires minimal configuration.

Debug Mode

Check Script Loading

Verify Plausible script is loaded correctly:

// Check if Plausible script exists
const plausibleScript = document.querySelector('script[src*="plausible.io"]');
if (plausibleScript) {
  console.log('Plausible script loaded');
  console.log('Script URL:', plausibleScript.src);
} else {
  console.error('Plausible script not found');
}

// Check if plausible function exists
if (typeof window.plausible !== 'undefined') {
  console.log('Plausible function available');
} else {
  console.log('Plausible function not available (may be using proxy)');
}

Monitor Network Requests

// Monitor Plausible network requests
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    if (entry.name.includes('plausible.io') ||
        entry.name.includes('/api/event')) {
      console.log('Plausible request:', entry.name);
      console.log('Duration:', entry.duration, 'ms');
    }
  });
});

observer.observe({ entryTypes: ['resource'] });

Common Issues

No Data in Dashboard

Symptoms: Tracking code installed but no data appears in Plausible.

Solutions:

  1. Verify script installation:
<!-- Standard Plausible script -->
<script defer data-domain="yourdomain.com" src="https://plausible.io/js/script.js"></script>

<!-- For self-hosted Plausible -->
<script defer data-domain="yourdomain.com" src="https://analytics.yourdomain.com/js/script.js"></script>

<!-- For extended features (outbound links, file downloads) -->
<script defer data-domain="yourdomain.com" src="https://plausible.io/js/script.outbound-links.js"></script>
  1. Check domain configuration:
<!-- data-domain must match your site's domain exactly -->
<script defer data-domain="example.com" src="https://plausible.io/js/script.js"></script>

<!-- For www subdomain -->
<script defer data-domain="www.example.com" src="https://plausible.io/js/script.js"></script>

<!-- Multiple domains on same site (rare) -->
<script defer data-domain="example.com,www.example.com" src="https://plausible.io/js/script.js"></script>

  1. Verify network requests:

    • Open DevTools → Network tab
    • Filter by "plausible" or "event"
    • Look for POST requests to /api/event
    • Status should be 202 (Accepted)

  2. Check for ad blockers:

    • Plausible is lightweight and privacy-focused
    • Still may be blocked by some ad blockers
    • Test in incognito mode
    • Consider using custom domain proxy

  3. Wait for data processing:

    • Data appears within seconds
    • Check "Last 30 min" view for real-time data
    • Refresh dashboard

Custom Events Not Tracking

Symptoms: Custom events aren't appearing in Plausible.

Solutions:

  1. Use plausible() function correctly:
// Track custom event
if (typeof window.plausible !== 'undefined') {
  plausible('Button Click');
} else {
  console.error('Plausible function not available');
}

// With custom properties (requires custom props extension)
plausible('Purchase', {
  props: {
    amount: '99.99',
    currency: 'USD'
  }
});
  1. Include custom events script:
<!-- Standard script doesn't support custom events -->
<!-- Use this instead: -->
<script defer data-domain="yourdomain.com" src="https://plausible.io/js/script.js"></script>

<!-- For custom events with properties: -->
<script defer data-domain="yourdomain.com" src="https://plausible.io/js/script.tagged-events.js"></script>
  1. Check event naming:
    • Event names are case-sensitive
    • Use descriptive names
    • Avoid special characters
// Good event names
plausible('Signup Completed');
plausible('Video Played');
plausible('Download PDF');

// Less clear
plausible('event1');
plausible('click');
  1. Define goals in Plausible:
    • Go to Settings → Goals
    • Add custom event name
    • Event must match exactly (case-sensitive)

Page Views Not Tracking

Symptoms: Some pages not appearing in Plausible dashboard.

Solutions:

  1. Verify script on all pages:
// Check if script exists on current page
const script = document.querySelector('script[data-domain]');
if (script) {
  console.log('Plausible script found');
  console.log('Domain:', script.getAttribute('data-domain'));
} else {
  console.error('Plausible script missing on this page');
}
  1. For single-page applications (SPAs):
// Manually trigger page view in SPAs
// After route change in React, Vue, etc.
if (typeof window.plausible !== 'undefined') {
  plausible('pageview');
}

// Example with React Router
import { useLocation } from 'react-router-dom';

function App() {
  const location = useLocation();

  useEffect(() => {
    plausible('pageview');
  }, [location]);
}
  1. Check excluded pages:
    • Go to Settings → Excluded Pages
    • Verify page isn't excluded
    • Remove if listed incorrectly

Symptoms: Clicks on external links aren't being tracked.

Solutions:

  1. Use correct script extension:
<!-- Use outbound-links extension -->
<script defer data-domain="yourdomain.com"
        src="https://plausible.io/js/script.outbound-links.js"></script>

<!-- Or combine multiple extensions -->
<script defer data-domain="yourdomain.com"
        src="https://plausible.io/js/script.outbound-links.file-downloads.js"></script>
  1. Add plausible-event-name attribute:
<!-- Track specific outbound links -->
<a href="https://external.com" class="plausible-event-name=External+Link">
  Visit External Site
</a>

<!-- Track with custom name -->
<a href="https://partner.com" class="plausible-event-name=Partner+Click">
  Partner Site
</a>
  1. Create goals for outbound links:
    • Go to Settings → Goals
    • Add goal: Outbound Link: Click
    • Specify URL pattern if needed

File Downloads Not Tracking

Symptoms: File download events not appearing.

Solutions:

  1. Include file-downloads extension:
<script defer data-domain="yourdomain.com"
        src="https://plausible.io/js/script.file-downloads.js"></script>
  1. Verify file extensions:
// Default tracked extensions:
// .pdf, .xlsx, .docx, .txt, .rtf, .csv, .exe, .dmg, .pkg, .deb, .zip

// Add custom event name for specific files
<a href="/whitepaper.pdf" class="plausible-event-name=Whitepaper+Download">
  Download PDF
</a>
  1. Create download goal:
    • Go to Settings → Goals
    • Add goal: File Download
    • Optionally filter by filename

Browser-Specific Issues

Safari ITP (Intelligent Tracking Prevention)

// Plausible is privacy-focused and uses no cookies by default
// Not affected by Safari ITP
// Uses localStorage for session tracking
console.log('Plausible uses cookieless tracking - ITP not an issue');

Content Security Policy (CSP)

<!-- Add Plausible domains to CSP -->
<meta http-equiv="Content-Security-Policy"
      content="script-src 'self' https://plausible.io;
               connect-src 'self' https://plausible.io;">

<!-- For self-hosted -->
<meta http-equiv="Content-Security-Policy"
      content="script-src 'self' https://analytics.yourdomain.com;
               connect-src 'self' https://analytics.yourdomain.com;">

Ad Blockers

Solutions:

  1. Use custom domain proxy:
<!-- Setup proxy to serve Plausible from your domain -->
<!-- This bypasses most ad blockers -->
<script defer data-domain="yourdomain.com"
        src="https://yourdomain.com/js/script.js"></script>
  1. Configure proxy in your server:
# Nginx example
location = /js/script.js {
    proxy_pass https://plausible.io/js/script.js;
    proxy_set_header Host plausible.io;
}

location = /api/event {
    proxy_pass https://plausible.io/api/event;
    proxy_set_header Host plausible.io;
}
  1. Test if blocked:
// Detect if Plausible is blocked
setTimeout(function() {
  const script = document.querySelector('script[src*="plausible"]');
  const scriptLoaded = script && script.getAttribute('data-domain');

  if (!scriptLoaded) {
    console.warn('Plausible may be blocked by ad blocker');
    // Consider server-side fallback
  }
}, 2000);

Self-Hosted Plausible Issues

Installation Problems

Solutions:

  1. Check Docker containers running:
# Verify containers are running
docker ps | grep plausible

# Should see:
# - plausible_db (PostgreSQL)
# - plausible_events_db (ClickHouse)
# - plausible (main app)
  1. Check logs:
# View Plausible logs
docker logs plausible

# Check for errors
docker logs plausible 2>&1 | grep -i error
  1. Verify database connection:
# Connect to PostgreSQL
docker exec -it plausible_db psql -U postgres -d plausible_db

# Check ClickHouse
docker exec -it plausible_events_db clickhouse-client

Custom Domain Configuration

<!-- Update script src to your domain -->
<script defer data-domain="yourdomain.com"
        src="https://analytics.yourdomain.com/js/script.js"></script>

# Update BASE_URL in plausible-conf.env
BASE_URL=https://analytics.yourdomain.com

Data Quality Issues

Duplicate Page Views

// Plausible automatically deduplicates page views
// If seeing duplicates, check for:

// 1. Multiple script tags
const scripts = document.querySelectorAll('script[data-domain]');
console.log('Number of Plausible scripts:', scripts.length);
if (scripts.length > 1) {
  console.error('Multiple Plausible scripts detected!');
}

// 2. Manual pageview calls in addition to auto-tracking
// Don't call plausible('pageview') unless in SPA

Bot Traffic

// Plausible filters known bots automatically
// No configuration needed

// Check if current visitor is a bot
if (/bot|crawler|spider/i.test(navigator.userAgent)) {
  console.log('Bot detected - Plausible will not track');
}

Referrer Issues

<!-- If referrer data missing, check meta tags -->
<meta name="referrer" content="no-referrer">

<!-- Change to: -->
<meta name="referrer" content="origin">
<!-- or -->
<meta name="referrer" content="strict-origin-when-cross-origin">

Debugging Techniques

Verify Tracking

// Complete Plausible diagnostic
function checkPlausible() {
  console.group('Plausible Diagnostic');

  // 1. Check script exists
  const script = document.querySelector('script[data-domain]');
  if (script) {
    console.log('✓ Script found');
    console.log('  Domain:', script.getAttribute('data-domain'));
    console.log('  Source:', script.src);
  } else {
    console.error('✗ Script not found');
  }

  // 2. Check function available
  if (typeof window.plausible !== 'undefined') {
    console.log('✓ plausible() function available');

    // Test event
    plausible('Diagnostic Test');
    console.log('✓ Test event sent');
  } else {
    console.log('○ plausible() function not available');
    console.log('  (Normal if using proxy or basic script)');
  }

  // 3. Check network requests
  console.log('Check Network tab for POST to /api/event');

  console.groupEnd();
}

checkPlausible();

Test Custom Events

// Test custom event tracking
function testPlausibleEvents() {
  if (typeof window.plausible === 'undefined') {
    console.error('Plausible function not available');
    console.log('Ensure you are using script.js (not script.manual.js)');
    return;
  }

  console.log('Sending test events...');

  // Simple event
  plausible('Test Event 1');

  // Event with properties
  plausible('Test Event 2', {
    props: {
      test_property: 'value',
      number: 123
    }
  });

  console.log('Check Plausible dashboard in ~30 seconds');
}

testPlausibleEvents();

Getting Help

Check Plausible Status

Visit status.plausible.io for service status.

Plausible Documentation

Visit plausible.io/docs for:

  • Installation guides
  • Script extensions
  • Custom events
  • API documentation

Community Support

  1. GitHub Discussions:

  2. Contact Support:

Best Practices

Regular Testing

// Create simple test function
function testPlausibleTracking() {
  console.group('Plausible Tests');

  // 1. Verify script
  const script = document.querySelector('script[data-domain]');
  console.log('Script present:', !!script);

  // 2. Check domain matches
  if (script) {
    const domain = script.getAttribute('data-domain');
    const currentDomain = window.location.hostname;
    console.log('Configured domain:', domain);
    console.log('Current domain:', currentDomain);

    if (!domain.includes(currentDomain) && !currentDomain.includes(domain)) {
      console.warn('Domain mismatch!');
    }
  }

  // 3. Test event tracking
  if (typeof window.plausible !== 'undefined') {
    plausible('Test Event');
    console.log('✓ Test event sent');
  }

  console.groupEnd();
}

testPlausibleTracking();

Monitoring

// Monitor Plausible in production
window.addEventListener('error', function(e) {
  if (e.filename && e.filename.includes('plausible')) {
    console.error('Plausible error:', e);
    // Alert monitoring service
  }
});

// Check script loaded
window.addEventListener('load', function() {
  setTimeout(function() {
    const script = document.querySelector('script[data-domain]');
    if (!script) {
      console.error('Plausible script not loaded after page load');
      // Alert monitoring service
    }
  }, 1000);
});

Testing Checklist

  • Plausible script tag present on all pages
  • data-domain attribute matches site domain
  • Script loads successfully (check Network tab)
  • Page views appearing in dashboard
  • Custom events configured (if used)
  • Goals defined for important events
  • Outbound links tracking (if enabled)
  • File downloads tracking (if enabled)
  • No JavaScript console errors
  • Network requests return 202 status
  • Data appearing within 1 minute
返回顶部