Understanding and Monitoring Realtime Heartbeats

[supabase-search[bot]]

This is a copy of a troubleshooting article on Supabase's docs site. It may be missing some details from the original. View the original article.

What are heartbeat messages?

Heartbeat messages are periodic signals sent between the Realtime client and server to verify that the WebSocket connection is alive and functioning properly. The client sends a heartbeat message on the phoenix topic with the event type heartbeat at regular intervals (default: 25 seconds), and the server responds with a phx_reply message.

These messages serve as a keep-alive mechanism to detect connection issues that might not be immediately apparent, such as silent network failures or intermediary proxy timeouts.

Why heartbeats matter

Heartbeat messages are critical for maintaining reliable real-time connections:

• Connection health monitoring: They detect when a connection has silently failed without triggering WebSocket close events
• Automatic recovery: When heartbeats time out, the client automatically attempts to reconnect
• Network proxy compatibility: Many network proxies and load balancers close idle connections; heartbeats keep the connection active
• Early issue detection: Heartbeat timeouts alert you to connection problems before users experience message delivery failures

Without heartbeats, your application might appear connected while being unable to send or receive messages.

How to handle heartbeat messages

You can monitor heartbeat lifecycle events using the onHeartbeat method:

import { createClient } from '@supabase/supabase-js'
import { useEffect } from 'react'

function MyComponent() {
  const supabase = createClient(SUPABASE_URL, SUPABASE_KEY)

  useEffect(() => {
    supabase.realtime.onHeartbeat((status) => {
      console.log('Heartbeat status:', status)
      // status can be: 'sent', 'ok', 'error', 'timeout', or 'disconnected'
    })
  }, [supabase])

  return <div>Your app content</div>
}

Or configure the callback during client initialization:

const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, {
  realtime: {
    heartbeatCallback: (status) => {
      console.log('Heartbeat status:', status)
    },
  },
})

Troubleshooting heartbeat issues

Frequent heartbeat timeouts

If you're seeing frequent timeout status in your heartbeat callback:

• Network instability: Check your network connection quality
• Firewall/proxy issues: Corporate firewalls or proxies might interfere with WebSocket connections
• Mobile app suspension: On mobile, the app can be suspended which can stop the heartbeat timers

Connection not reconnecting after timeout

The client automatically attempts reconnection with exponential backoff (1s, 2s, 5s, 10s). If you need to manually reconnect:

import { createClient } from '@supabase/supabase-js'
import { useEffect, useState } from 'react'

function ConnectionStatus() {
  const supabase = createClient(SUPABASE_URL, SUPABASE_KEY)
  const [isConnected, setIsConnected] = useState(true)

  useEffect(() => {
    supabase.realtime.onHeartbeat((status) => {
      if (status === 'ok') {
        setIsConnected(true)
      } else if (status === 'timeout' || status === 'disconnected') {
        setIsConnected(false)
      }
    })
  }, [supabase])

  const handleReconnect = () => {
    supabase.realtime.connect()
  }

  return (
    <div>
      <p>Status: {isConnected ? 'Connected' : 'Disconnected'}</p>
      {!isConnected && <button onClick={handleReconnect}>Reconnect</button>}
    </div>
  )
}

Customizing heartbeat interval

You can adjust the heartbeat frequency when creating your Supabase client in React:

import { createClient } from '@supabase/supabase-js'
import { useMemo } from 'react'

function App() {
  const supabase = useMemo(
    () =>
      createClient(SUPABASE_URL, SUPABASE_KEY, {
        realtime: {
          heartbeatIntervalMs: 15000, // Send heartbeat every 15 seconds (default: 25000)
        },
      }),
    []
  )

  return <YourApp supabase={supabase} />
}

Note: Increasing the interval reduces network traffic but delays detection of connection failures. Decreasing it improves detection speed but increases overhead.

Heartbeat errors in Web workers

For React applications with long-running connections, use Web Workers to prevent browser tab throttling:

import { createClient } from '@supabase/supabase-js'
import { useMemo } from 'react'

function App() {
  const supabase = useMemo(
    () =>
      createClient(SUPABASE_URL, SUPABASE_KEY, {
        realtime: {
          worker: true,
          workerUrl: '/worker.js', // Optional: Place in public folder
        },
      }),
    []
  )

  return <YourApp supabase={supabase} />
}

If the worker fails to start, check:

• Browser Web Worker support is available
• Worker script is in the public folder and accessible
• CORS headers allow loading the worker script

Best practices

Show connection status to users

Display connection status with an indicator:

import { createClient } from '@supabase/supabase-js'
import { useEffect, useState } from 'react'

function ConnectionIndicator() {
  const supabase = createClient(SUPABASE_URL, SUPABASE_KEY)
  const [status, setStatus] = useState('healthy')

  useEffect(() => {
    supabase.realtime.onHeartbeat((heartbeatStatus) => {
      if (heartbeatStatus === 'ok') {
        setStatus('healthy')
      } else if (heartbeatStatus === 'timeout') {
        setStatus('poor')
      } else if (heartbeatStatus === 'disconnected') {
        setStatus('disconnected')
      }
    })
  }, [supabase])

  return (
    <div>
      <span>Connection: {status}</span>
    </div>
  )
}

Reconnect when React Native app comes to foreground

Ensure connection is active when user opens your app:

import { createClient } from '@supabase/supabase-js'
import { useEffect } from 'react'
import { AppState } from 'react-native'

function App() {
  const supabase = createClient(SUPABASE_URL, SUPABASE_KEY)

  useEffect(() => {
    const subscription = AppState.addEventListener('change', (nextAppState) => {
      if (nextAppState === 'active') {
        if (!supabase.realtime.isConnected()) {
          supabase.realtime.connect()
        }
      }
    })

    return () => {
      subscription.remove()
    }
  }, [supabase])

  return <YourApp />
}

Monitor connection in your entire app

Set up monitoring when you create your Supabase client:

import { createClient } from '@supabase/supabase-js'

const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, {
  realtime: {
    heartbeatCallback: (status) => {
      if (status === 'ok') {
        console.log('Connection healthy')
      } else if (status === 'timeout') {
        console.warn('Connection slow')
      } else if (status === 'disconnected') {
        console.error('Disconnected')
      }
    },
  },
})

export default supabase