🔔 Debugging push notifications

Trace why a user is not receiving GetStream push notifications by inspecting the feed subscription graph.

This is what the server is for. When a user reports that push notifications have stopped arriving in a GetStream-powered app, the cause is almost always a broken feed subscription — and this server lets you find and fix it in a conversation.

🧠 The mental model

GetStream delivers notifications by fan-out through follow relationships. A user's notification feed receives an activity only if it follows the feed that produced it. The chain looks like this:

producing feed  →  (follow relationship)  →  user's notification feed  →  push

Break any link and the push never fires. The most common break is a missing follow: notification:user_123 simply does not follow the feed it should.

🔍 Step-by-step investigation

1. Confirm what the user's feed is subscribed to

You: "Is user_123 subscribed to the timeline feed?"
AI:  Calls getstream_feed_following with feed_slug=notification, feed_id=user_123
     and checks whether timeline:timeline_global appears in the results.

If the expected target is missing from the following list, you have found the root cause: the subscription was never created or was removed.

2. Cross-check from the other side

You: "How many users are subscribed to timeline_global?"
AI:  Calls getstream_feed_followers with feed_slug=timeline,
     feed_id=timeline_global and returns the count.

This confirms whether the target feed has followers at all, and whether the affected user appears among them.

3. Verify activity is actually being produced

You: "Show me the last 5 activities on the user_activity feed for user_123."
AI:  Calls getstream_feed_activities with feed_slug=user_activity,
     feed_id=user_123, limit=5.

If there are no recent activities, the problem is upstream of delivery — nothing is being produced to fan out.

4. Fix the missing subscription

Once you have confirmed the gap, repair it in place:

You: "Subscribe user_123 to timeline_global."
AI:  Calls getstream_feed_follow with
     source_feed_slug=notification, source_feed_id=user_123,
     target_feed_slug=timeline, target_feed_id=timeline_global, confirm=true.

The confirm: true safety gate ensures the follow only happens when you mean it.

5. Remove an unwanted subscription

The inverse — when a user is receiving notifications they should not be:

You: "Unsubscribe user_456 from user_activity:user_456."
AI:  Calls getstream_feed_unfollow with
     source_feed_slug=notification, source_feed_id=user_456,
     target_feed_slug=user_activity, target_feed_id=user_456, confirm=true.

💡 The one-line diagnosis

You: "Why isn't this user receiving notifications?"
AI:  Checks their notification feed's following list. If the expected target
     (e.g. timeline:timeline_global) is missing, the missing subscription is
     the root cause.

That single check — what does the notification feed follow? — resolves the majority of "I stopped getting notifications" reports.

🔔 Debugging push notifications

On this page