react-fathomv0.3.0
On this page
  1. Events Not Appearing
  2. 1. Verify Your Site ID
  3. 2. Check for Ad Blockers
  4. 3. Domain Restrictions
  5. 4. Inspect Network Requests
  6. Duplicate Pageviews
  7. Next.js Issues
  8. "use client" Errors
  9. Environment Variables Not Loading
  10. React Native Issues
  11. Events Not Sending
  12. 1. Verify react-native-webview is installed
  13. 2. Check WebView is ready
  14. 3. Verify network connectivity
  15. 4. Check for WebView restrictions
  16. Queue Not Flushing
  17. Debugging Tips
  18. Enable Debug Logging
  19. Use a Console Client
  20. Verify Real-time in Dashboard
  21. Getting Help

Troubleshooting

Common issues and solutions for react-fathom.

Events Not Appearing

1. Verify Your Site ID

Your site ID should match exactly what's in your Fathom dashboard. It's an 8-character alphanumeric string like ABCD1234.

tsx
// Double-check this value
<FathomProvider siteId="ABCD1234">

2. Check for Ad Blockers

Many ad blockers and privacy extensions block analytics scripts. To test:

  • Open an incognito/private window with extensions disabled
  • Or temporarily whitelist your development domain

Consider using custom domains to improve tracking reliability.

3. Domain Restrictions

Fathom only tracks events from configured domains. For local development:

tsx
<FathomProvider
  siteId="YOUR_SITE_ID"
  clientOptions={{
    includedDomains: ['localhost', 'yourdomain.com']
  }}
>

4. Inspect Network Requests

Open your browser's Network tab and look for requests to cdn.usefathom.com:

SymptomCause
No requestsScript isn't loading—check provider setup
Blocked requestsAd blocker interference
Failed requestsCheck site ID and domain configuration

Duplicate Pageviews

If you see double pageviews, you have multiple tracking sources:

tsx
// WRONG: NextFathomTrackViewApp tracks AND clientOptions.auto defaults to true
<FathomProvider siteId="YOUR_SITE_ID">
  <NextFathomTrackViewApp />
</FathomProvider>

// CORRECT: Disable fathom-client's built-in auto tracking
<FathomProvider siteId="YOUR_SITE_ID" clientOptions={{ auto: false }}>
  <NextFathomTrackViewApp />
</FathomProvider>

Same applies to NextFathomProviderApp:

tsx
<NextFathomProviderApp siteId="YOUR_SITE_ID" clientOptions={{ auto: false }}>
  {children}
</NextFathomProviderApp>

Next.js Issues

"use client" Errors

Server Components can't use hooks directly. Use the pre-configured client component:

tsx
// app/layout.tsx
import { NextFathomProviderApp } from 'react-fathom/next'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <NextFathomProviderApp siteId="YOUR_SITE_ID">
          {children}
        </NextFathomProviderApp>
      </body>
    </html>
  )
}

Or create your own client component wrapper:

tsx
// components/AnalyticsProvider.tsx
'use client'
import { FathomProvider } from 'react-fathom'

export function AnalyticsProvider({ children }) {
  return (
    <FathomProvider siteId={process.env.NEXT_PUBLIC_FATHOM_SITE_ID}>
      {children}
    </FathomProvider>
  )
}

Environment Variables Not Loading

Ensure your variable is prefixed with NEXT_PUBLIC_:

bash
# .env.local
NEXT_PUBLIC_FATHOM_SITE_ID=YOUR_SITE_ID  # ✓ Works client-side
FATHOM_SITE_ID=YOUR_SITE_ID               # ✗ Server-only

React Native Issues

Events Not Sending

1. Verify react-native-webview is installed

bash
npm install react-native-webview

# For iOS
cd ios && pod install

2. Check WebView is ready

Events are queued until the WebView loads:

tsx
<NativeFathomProvider
  siteId="YOUR_SITE_ID"
  debug={true}
  onReady={() => console.log('Fathom WebView ready!')}
  onError={(err) => console.error('Fathom error:', err)}
>

3. Verify network connectivity

The WebView needs network access to load the Fathom script from cdn.usefathom.com (or your custom domain).

4. Check for WebView restrictions

Some enterprise MDM solutions or app configurations block WebViews from loading external scripts.

Queue Not Flushing

If events stay queued:

  1. Check onReady is being called
  2. Verify no onError is firing
  3. Use debug={true} to see queue activity
tsx
const clientRef = useRef(null)

<NativeFathomProvider siteId="YOUR_SITE_ID" clientRef={clientRef}>
  {/* Check queue length */}
  {console.log('Queue:', clientRef.current?.getQueueLength())}
</NativeFathomProvider>

Debugging Tips

Enable Debug Logging

For React Native:

tsx
<NativeFathomProvider
  siteId="YOUR_SITE_ID"
  debug={__DEV__}
>

Use a Console Client

Replace the real client with one that logs everything:

tsx
const debugClient = {
  load: (id, opts) => console.log('load:', id, opts),
  trackPageview: (opts) => console.log('pageview:', opts),
  trackEvent: (name, opts) => console.log('event:', name, opts),
  trackGoal: (code, cents) => console.log('goal:', code, cents),
  setSite: (id) => console.log('setSite:', id),
  blockTrackingForMe: () => console.log('blocked'),
  enableTrackingForMe: () => console.log('enabled'),
  isTrackingEnabled: () => true,
}

<FathomProvider client={debugClient}>

Verify Real-time in Dashboard

Fathom's dashboard updates in real-time. Open it alongside your app to see events as they're tracked.

Getting Help

Last updated: October 8, 2026

By

Commune Software