Supabase Realtime Channel Requires Explicit Subscribe Call to Receive Events

Supabase Realtime channel is created and event handlers are registered with .on() but no events arrive. The code looks correct but the subscription never activates.

A Supabase Realtime channel does not start receiving events until .subscribe() is called. The callback passed to subscribe fires when the subscription is confirmed by the server.

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

const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY);

const channel = supabase
  .channel('table-changes')
  .on(
    'postgres_changes',
    { event: '*', schema: 'public', table: 'messages' },
    (payload) => {
      console.log('Change received:', payload);
    }
  )
  .subscribe((status) => {
    if (status === 'SUBSCRIBED') {
      console.log('Realtime subscription active');
    }
  }); // <-- this call is mandatory

// Cleanup
return () => { supabase.removeChannel(channel); };

Supabase Realtime uses a lazy activation model — channels are registered locally but the server-side subscription is only established when subscribe() is called. This allows batching multiple .on() handlers before connecting.