Mahdi BEN RHOUMA

Posted on Jun 17 • Originally published at iloveblogs.blog

Supabase Realtime Gotchas: 7 Issues and How to Fix Them

#supabase #realtime #websockets #nextjs

Supabase Realtime Gotchas: 7 Issues and How to Fix Them

Supabase Realtime is powerful for building collaborative, real-time features. But it's also a common source of bugs, memory leaks, and performance issues. I've debugged dozens of realtime issues in production applications, and most stem from a few common mistakes.

Here are the 7 most common Supabase Realtime gotchas and how to fix them.

1. Forgetting to Enable Realtime on Tables

The Problem:

You set up a realtime subscription, but you never receive any updates. You spend hours debugging, only to discover realtime wasn't enabled on the table.

// ❌ Bad: Realtime not enabled
'use client'

export function LivePosts() {
  const [posts, setPosts] = useState([])
  const supabase = createClient()

  useEffect(() => {
    // This subscription will never fire!
    const subscription = supabase
      .from('posts')
      .on('*', (payload) => {
        setPosts(prev => [...prev, payload.new])
      })
      .subscribe()

    return () => subscription.unsubscribe()
  }, [])

  return <div>{posts.map(p => <p key={p.id}>{p.title}</p>)}</div>
}

Why It Happens:

By default, Supabase doesn't enable Realtime on tables for security and performance reasons. You must explicitly enable it.

The Fix:

Enable Realtime in Supabase Dashboard:

Go to Database → Replication
Find your table
Toggle Realtime on

Or use SQL:

-- Enable realtime for a table
ALTER PUBLICATION supabase_realtime ADD TABLE posts;

-- Disable realtime for a table
ALTER PUBLICATION supabase_realtime DROP TABLE posts;

2. Memory Leaks from Unsubscribed Listeners

The Problem:

Your app works fine initially, but after a few hours, it becomes sluggish. Memory usage keeps growing. You have a memory leak from realtime subscriptions.

// ❌ Bad: Memory leak
'use client'

export function LivePosts() {
  const [posts, setPosts] = useState([])
  const supabase = createClient()

  useEffect(() => {
    const subscription = supabase
      .from('posts')
      .on('*', (payload) => {
        setPosts(prev => [...prev, payload.new])
      })
      .subscribe()

    // Missing: unsubscribe on cleanup!
  }, [])

  return <div>{posts.map(p => <p key={p.id}>{p.title}</p>)}</div>
}

Why It Leaks:

The subscription stays active even after the component unmounts. Each time the component remounts, a new subscription is created. After many mounts/unmounts, you have dozens of active subscriptions consuming memory.

The Fix:

Always unsubscribe in the cleanup function:

// ✅ Good: Proper cleanup
'use client'

export function LivePosts() {
  const [posts, setPosts] = useState([])
  const supabase = createClient()

  useEffect(() => {
    const subscription = supabase
      .from('posts')
      .on('*', (payload) => {
        setPosts(prev => [...prev, payload.new])
      })
      .subscribe()

    // Cleanup: unsubscribe when component unmounts
    return () => {
      subscription.unsubscribe()
    }
  }, [])

  return <div>{posts.map(p => <p key={p.id}>{p.title}</p>)}</div>
}

Pro Tip: Use React DevTools Profiler to detect memory leaks. Watch memory usage as you navigate between pages.

3. Duplicate Subscriptions Causing Duplicate Events

The Problem:

You receive the same event twice. Or three times. Or more. Your UI updates multiple times for a single database change.

// ❌ Bad: Duplicate subscriptions
'use client'

export function LivePosts() {
  const [posts, setPosts] = useState([])
  const supabase = createClient()

  // This runs twice in development (React StrictMode)
  // and creates duplicate subscriptions
  useEffect(() => {
    const subscription = supabase
      .from('posts')
      .on('*', (payload) => {
        setPosts(prev => [...prev, payload.new])
      })
      .subscribe()

    return () => subscription.unsubscribe()
  }, []) // Missing dependency tracking

  return <div>{posts.map(p => <p key={p.id}>{p.title}</p>)}</div>
}

Why It Happens:

In React development mode (StrictMode), effects run twice to detect side effects. If you're not careful, you create duplicate subscriptions. Also, if you subscribe multiple times in the same component, you get duplicate events.

The Fix:

Use a ref to track subscription state:

// ✅ Good: Prevent duplicate subscriptions
'use client'

export function LivePosts() {
  const [posts, setPosts] = useState([])
  const subscriptionRef = useRef(null)
  const supabase = createClient()

  useEffect(() => {
    // Only subscribe once
    if (subscriptionRef.current) return

    const subscription = supabase
      .from('posts')
      .on('*', (payload) => {
        setPosts(prev => [...prev, payload.new])
      })
      .subscribe()

    subscriptionRef.current = subscription

    return () => {
      subscription.unsubscribe()
      subscriptionRef.current = null
    }
  }, [])

  return <div>{posts.map(p => <p key={p.id}>{p.title}</p>)}</div>
}

4. RLS Policies Blocking Realtime Updates

The Problem:

Realtime subscriptions work in development but fail in production. You're not receiving any updates.

// ❌ Bad: RLS policy blocks realtime
'use client'

export function UserPosts() {
  const [posts, setPosts] = useState([])
  const supabase = createClient()

  useEffect(() => {
    // This subscription fails silently if RLS policy denies access
    const subscription = supabase
      .from('posts')
      .on('*', (payload) => {
        setPosts(prev => [...prev, payload.new])
      })
      .subscribe()

    return () => subscription.unsubscribe()
  }, [])

  return <div>{posts.map(p => <p key={p.id}>{p.title}</p>)}</div>
}

Why It Fails:

Realtime respects RLS policies. If your RLS policy denies access, the subscription silently fails. You won't see an error—you just won't receive updates.

The Fix:

Ensure your RLS policies allow realtime subscriptions:

-- ✅ Good: RLS policy allows realtime
CREATE POLICY "Users can view own posts"
  ON posts FOR SELECT
  USING (auth.uid() = user_id);

-- Test the policy
SELECT * FROM posts WHERE auth.uid() = user_id;

Debug Tip: Check browser console for realtime errors. Enable debug logging:

supabase.realtime.setAuth(token)

5. Not Handling Realtime Reconnection

The Problem:

The user's internet drops for a few seconds. The realtime connection is lost. They don't receive updates until they refresh the page.

// ❌ Bad: No reconnection handling
'use client'

export function LivePosts() {
  const [posts, setPosts] = useState([])
  const supabase = createClient()

  useEffect(() => {
    const subscription = supabase
      .from('posts')
      .on('*', (payload) => {
        setPosts(prev => [...prev, payload.new])
      })
      .subscribe()

    // Missing: handle disconnection and reconnection
    return () => subscription.unsubscribe()
  }, [])

  return <div>{posts.map(p => <p key={p.id}>{p.title}</p>)}</div>
}

Why It Fails:

Network interruptions are inevitable. If you don't handle reconnection, users miss updates.

The Fix:

Listen for connection state changes:

// ✅ Good: Handle reconnection
'use client'

export function LivePosts() {
  const [posts, setPosts] = useState([])
  const [isConnected, setIsConnected] = useState(true)
  const supabase = createClient()

  useEffect(() => {
    const subscription = supabase
      .from('posts')
      .on('*', (payload) => {
        setPosts(prev => [...prev, payload.new])
      })
      .subscribe(
        (status) => {
          setIsConnected(status === 'SUBSCRIBED')
        }
      )

    return () => subscription.unsubscribe()
  }, [])

  return (
    <div>
      {!isConnected && <p>Reconnecting...</p>}
      {posts.map(p => <p key={p.id}>{p.title}</p>)}
    </div>
  )
}

6. Realtime in Server Components

The Problem:

You try to use realtime in a Server Component, but it doesn't work. You get errors about browser APIs.

// ❌ Bad: Realtime in Server Component
export default async function PostsPage() {
  const supabase = createServerClient()

  // This doesn't work! Realtime requires WebSocket (browser only)
  const subscription = supabase
    .from('posts')
    .on('*', (payload) => {
      console.log(payload)
    })
    .subscribe()

  return <div>Posts</div>
}

Why It Fails:

Realtime uses WebSocket connections, which only work in browsers. Server Components run on the server and don't have WebSocket support.

The Fix:

Use Client Components for realtime:

// ✅ Good: Realtime in Client Component
'use client'

export function LivePosts() {
  const [posts, setPosts] = useState([])
  const supabase = createClient()

  useEffect(() => {
    const subscription = supabase
      .from('posts')
      .on('*', (payload) => {
        setPosts(prev => [...prev, payload.new])
      })
      .subscribe()

    return () => subscription.unsubscribe()
  }, [])

  return <div>{posts.map(p => <p key={p.id}>{p.title}</p>)}</div>
}

7. Large Payloads Slowing Down Realtime

The Problem:

Realtime updates are slow. Each update takes several seconds to process. Your UI feels sluggish.

// ❌ Bad: Large payloads
'use client'

export function LivePosts() {
  const [posts, setPosts] = useState([])
  const supabase = createClient()

  useEffect(() => {
    // Fetching ALL columns, including large text fields
    const subscription = supabase
      .from('posts')
      .on('*', (payload) => {
        setPosts(prev => [...prev, payload.new])
      })
      .subscribe()

    return () => subscription.unsubscribe()
  }, [])

  return <div>{posts.map(p => <p key={p.id}>{p.title}</p>)}</div>
}

Why It's Slow:

You're sending large payloads over the WebSocket. If your posts table has large text fields, each update sends megabytes of data.

The Fix:

Select only the columns you need:

// ✅ Good: Minimal payloads
'use client'

export function LivePosts() {
  const [posts, setPosts] = useState([])
  const supabase = createClient()

  useEffect(() => {
    // Only select needed columns
    const subscription = supabase
      .from('posts')
      .on('*', (payload) => {
        setPosts(prev => [...prev, payload.new])
      })
      .select('id, title, created_at') // Only these columns
      .subscribe()

    return () => subscription.unsubscribe()
  }, [])

  return <div>{posts.map(p => <p key={p.id}>{p.title}</p>)}</div>
}

Realtime Debugging Checklist

✅ Realtime enabled on the table (Database → Replication)
✅ RLS policies allow access
✅ Subscriptions cleaned up on unmount
✅ No duplicate subscriptions
✅ Only selecting needed columns
✅ Handling reconnection
✅ Using Client Components (not Server Components)
✅ Monitoring memory usage
✅ Testing with network throttling

Conclusion

Supabase Realtime is incredibly powerful, but it requires careful handling. Enable realtime on tables, always unsubscribe, prevent duplicate subscriptions, and handle reconnection. With these practices, you'll build smooth, real-time features that delight users.

The key is testing thoroughly—especially with network throttling and connection interruptions. That's where most realtime bugs hide.

Originally published at https://www.iloveblogs.blog