Notes from a 2 AM On-Call: Supabase Realtime Connection Reset Under Next.js SSR Load

The Failure Symptom

[supabase-js] RealtimeClient connection error: Error: WebSocket closed with code 1006
[Next.js] TypeError: Cannot read properties of undefined (reading 'channel')
[Vercel] Function invocation timeout after 10s

Production dashboard went dark at 1:47 AM. No client errors. Server logs showed Supabase Realtime subscriptions silently dropping after 8-12 seconds under concurrent Server Component render load. The kicker? Local dev was flawless. Staging with 10 concurrent users worked. Production with 200+ simultaneous SSR requests collapsed.

The Red Herring

Every Next.js + Supabase tutorial shows this Server Component pattern:

// app/dashboard/page.tsx
import { createClient } from '@/lib/supabase/server'

export default async function Dashboard() {
  const supabase = createClient()
  const channel = supabase
    .channel('public:events')
    .on('postgres_changes', 
      { event: '*', schema: 'public', table: 'events' },
      (payload) => console.log(payload)
    )
    .subscribe()

  const { data } = await supabase.from('events').select()
  return <EventList events={data} />
}

Under Next.js 15 concurrent RSC streaming, each render creates a new Supabase client instance with a fresh Realtime connection. With 50 users hitting the dashboard simultaneously, we spawned 50+ WebSocket connections to Supabase Realtime within 2 seconds. Supabase's connection pooling throttled us. Connections queued, timed out at 10s, then cascaded into retry storms.

The misleading part? createClient() in Server Components feels stateless and React-idiomatic. But Realtime WebSockets are stateful long-lived TCP connections. React's render concurrency model conflicts with connection pool limits (Supabase Free: 60 concurrent, Pro: 500).

The Root Cause & Runnable Fix

Realtime subscriptions belong in Client Components with singleton connection management, not Server Components. Server Components should handle initial data fetch only.

Fixed Architecture

1. Server Component (RSC) — Initial Data Only

// app/dashboard/page.tsx
import { createClient } from '@/lib/supabase/server'
import { RealtimeEvents } from './realtime-events'

export default async function Dashboard() {
  const supabase = createClient()
  const { data: initialEvents } = await supabase
    .from('events')
    .select()
    .order('created_at', { ascending: false })
    .limit(50)

  return <RealtimeEvents initialEvents={initialEvents} />
}

2. Client Component — Singleton Realtime Connection

// app/dashboard/realtime-events.tsx
'use client'

import { createClient } from '@/lib/supabase/client'
import { useEffect, useState } from 'react'
import type { RealtimeChannel } from '@supabase/supabase-js'

let globalChannel: RealtimeChannel | null = null

export function RealtimeEvents({ initialEvents }) {
  const [events, setEvents] = useState(initialEvents)
  const supabase = createClient()

  useEffect(() => {
    if (!globalChannel) {
      globalChannel = supabase
        .channel('events-feed')
        .on('postgres_changes',
          { event: '*', schema: 'public', table: 'events' },
          (payload) => {
            setEvents((prev) => [payload.new, ...prev].slice(0, 50))
          }
        )
        .subscribe((status) => {
          if (status === 'SUBSCRIBED') {
            console.log('[Realtime] Connected')
          }
        })
    }

    return () => {
      // Keep connection alive across component remounts
      // Only cleanup on actual unmount (e.g., route navigation)
    }
  }, [])

  return (
    <ul>
      {events.map((event) => (
        <li key={event.id}>{event.title}</li>
      ))}
    </ul>
  )
}

Key Fix: Module-level globalChannel singleton prevents duplicate subscriptions across React StrictMode double-renders and Fast Refresh. Connection count dropped from 50+ to 1 per client browser session.

Monitoring Addition

// lib/supabase/client.ts
import { createBrowserClient } from '@supabase/ssr'

export function createClient() {
  const client = createBrowserClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
  )

  client.realtime.onOpen(() => {
    console.log('[Realtime] WS open', new Date().toISOString())
  })

  client.realtime.onClose((event) => {
    console.error('[Realtime] WS closed', event.code, event.reason)
  })

  return client
}

After deployment: zero connection resets, consistent 1-2 second subscription latency even at 500 concurrent users.

Invariant Rule

Realtime subscriptions are stateful I/O—never instantiate them in Server Components or React render loops.

If your Server Component needs live data, fetch the baseline snapshot server-side, then hydrate the Client Component with a singleton Realtime subscription. This pattern applies to any WebSocket/SSE integration (Pusher, Ably, Socket.IO) under Next.js RSC concurrency.

Connection pooling isn't just a backend database concern—it governs client WebSocket fan-out too.