Debug Realtime with Logger and Log Levels

Last edited: 12/12/2025

What are logger and log_level parameters?

The Realtime client provides built-in logging to help you debug connection issues, track messages, and understand what's happening with your real-time connections. Two parameters control logging:

  • logger: A custom function to handle log messages
  • logLevel: Controls which messages the server logs (info, warn, or error)

By default, logging is disabled. When enabled, you can see:

  • Messages sent and received
  • Connection events (connect, disconnect, errors)
  • Heartbeat status
  • Channel subscriptions
  • Worker events

How to enable logging in your Realtime client

Basic logging to console

1
import { createClient } from '@supabase/supabase-js'
2
3
const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, {
4
  realtime: {
5
    logger: (kind, msg, data) => {
6
      console.log(`${kind}: ${msg}`, data)
7
    },
8
  },
9
})

With log levels for server-side filtering

1
const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, {
2
  realtime: {
3
    logLevel: 'info', // 'info' | 'warn' | 'error'
4
    logger: (kind, msg, data) => {
5
      console.log(`[${kind}] ${msg}`, data)
6
    },
7
  },
8
})

Understanding log messages

The logger receives three parameters: kind, msg, and data.

Log kinds you'll see:

push - Messages sent to the server

1
push: realtime:chat heartbeat (42) {}
2
push: realtime:chat phx_join (1) { config: {...} }

receive - Messages received from server

1
receive: ok realtime:chat phx_reply (1) { response: {...} }
2
receive: realtime:chat broadcast { event: 'message', payload: {...} }

transport - Connection events

1
transport: connected to wss://project.supabase.co/realtime/v1
2
transport: heartbeat timeout. Attempting to re-establish connection
3
transport: close CloseEvent {...}
4
transport: leaving duplicate topic "realtime:chat"

error - Error events

1
error: error in heartbeat callback Error: ...
2
error: error waiting for auth on connect Error: ...

worker - Web Worker events

1
worker: starting default worker
2
worker: starting worker for from /worker.js
3
worker: worker error message

Common debugging scenarios

Debug why channel won't subscribe:

1
import { createClient } from '@supabase/supabase-js'
2
3
const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, {
4
  realtime: {
5
    logger: (kind, msg, data) => {
6
      console.log(`[${kind}] ${msg}`, data)
7
    },
8
  },
9
})
10
11
const channel = supabase
12
  .channel('debug-channel')
13
  .on('broadcast', { event: 'test' }, (payload) => {
14
    console.log('Received:', payload)
15
  })
16
  .subscribe((status, err) => {
17
    console.log('Subscribe status:', status, err)
18
  })
19
20
// Check logs for:
21
// push: realtime:debug-channel phx_join - subscription attempt
22
// receive: ok realtime:debug-channel phx_reply - successful subscription
23
// Or error messages if subscription failed

Debug message delivery issues

1
const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, {
2
  realtime: {
3
    logger: (kind, msg, data) => {
4
      if (kind === 'push' || kind === 'receive') {
5
        console.log(`[${kind}] ${msg}`, data)
6
      }
7
    },
8
  },
9
})
10
11
const channel = supabase.channel('chat', { config: { broadcast: { self: true } } })
12
13
channel.on('broadcast', { event: 'message' }, (payload) => {
14
  console.log('Message received:', payload)
15
})
16
// Send message after subscribing
17
channel.subscribe((status, err) => {
18
  if (status == 'SUBSCRIBED') {
19
    channel.send({
20
      type: 'broadcast',
21
      event: 'message',
22
      payload: { text: 'Hello' },
23
    })
24
  } else {
25
    console.error({ status, err })
26
  }
27
})
28
29
// Check logs:
30
// push: realtime:chat broadcast - message sent
31
// receive: realtime:chat broadcast - message received (if self: true)