How to fix REALTIME_SUBSCRIPTION_ERROR: Failed to subscribe to channel in Supabase

1. Go to your Supabase project dashboard
2. Navigate to Database > Publications
3. Find or create the supabase_realtime publication
4. Add your target table to the publication
5. Select which events (INSERT, UPDATE, DELETE) you want to replicate

Without this step, Realtime cannot listen to database changes. This is disabled by default on new projects.

-- Alternatively, enable via SQL
ALTER PUBLICATION supabase_realtime ADD TABLE your_table_name;

If using Row Level Security (RLS), ensure the supabase_realtime role can read your table:

GRANT SELECT ON your_table_name TO supabase_realtime;

This grants Realtime permission to filter and broadcast events according to your RLS policies. Without this, subscriptions fail during authorization checks.

If you have RLS policies, they will still apply—this grant just allows Realtime to check them.

For private channels, set the auth token immediately after creating the Supabase client:

const { data: { session } } = await supabase.auth.getSession();
if (session?.access_token) {
  supabase.realtime.setAuth(session.access_token);
}

Do this before calling .subscribe(). The token is required for the server to authorize access to private channels.

Also subscribe to auth state changes to update the token when users sign in/out:

supabase.auth.onAuthStateChange((event, session) => {
  if (session?.access_token) {
    supabase.realtime.setAuth(session.access_token);
  } else {
    supabase.realtime.setAuth(null);
  }
});

Check that the channel name is correct and matches your configuration exactly. Channel names are case-sensitive.

// For database changes
const channel = supabase
  .channel('realtime:your_table_name')
  .on('postgres_changes', 
    { event: '*', schema: 'public', table: 'your_table_name' },
    (payload) => console.log(payload)
  )
  .subscribe((status, err) => {
    console.log('Subscription status:', status);
    if (err) console.error('Error:', err);
  });

// For broadcast
const channel = supabase
  .channel('my_broadcast_channel')
  .on('broadcast', { event: 'message' }, (payload) => console.log(payload))
  .subscribe((status, err) => {
    console.log('Subscription status:', status);
    if (err) console.error('Error:', err);
  });

Add the callback to .subscribe() to log the status and error details for debugging.

If using private channels with Realtime Authorization, define policies in the realtime.messages table:

-- Example: allow users to subscribe to their own channel
CREATE POLICY "allow-subscribe-policy" ON realtime.messages
  FOR SELECT USING (
    auth.uid()::text = (topic::jsonb ->> 'user_id')
  );

The policy determines which clients can subscribe to which channels. Ensure your policy logic matches your channel naming or metadata.

Realtime Authorization is in Public Beta. Use supabase-js v2.44.0 or later for this feature.

Verify your Supabase client is initialized with the correct API key:

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

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
);

Ensure:
- NEXT_PUBLIC_SUPABASE_URL is your project's URL (e.g., https://xyz.supabase.co)
- NEXT_PUBLIC_SUPABASE_ANON_KEY is copied exactly from your Supabase dashboard (check for cut-off characters)

If you recently changed keys or rotated them, update your .env.local file and restart your app.

Add comprehensive error logging to identify the exact failure point:

const channel = supabase
  .channel('my_channel')
  .on('postgres_changes', { event: '*', schema: 'public', table: 'my_table' },
    (payload) => console.log('Change:', payload)
  )
  .subscribe((status, err) => {
    console.log('Status:', status);
    if (err) {
      console.error('Subscription error:', err.message);
      console.error('Full error:', err);
    }
  });

Use the Realtime Inspector to verify your instance is healthy:
- Visit https://realtime.supabase.co/inspector/new
- This shows connection status and can reveal infrastructure issues

Check the Supabase dashboard under Realtime > Inspector for server-side logs and errors.