On this page

Status Events for JavaScript SDK

The PubNub JavaScript Software Development Kit (SDK) reports status events for subscription and connectivity. This page summarizes which statuses you can expect based on your subscription architecture.

Subscribe loop

The SDK emits different statuses depending on the subscription architecture you select: the default subscription manager, or the newer, recommended subscription architecture (introduced in version 7.5.0 and enabled with enableEventEngine: true).

The PubNub JavaScript SDK emits statuses to notify you about the state of the SDK.

SDK connection lifecycle

For more general information on statuses and reconnection policies, refer to SDK Connection Lifecycle.

Available statuses​

Depending on whether enableEventEngine is true or false, the SDK emits different statuses.


StatusDescriptionIntroduced in version
PNConnectedCategory
PubNub client subscribed and is ready to receive real-time updates. This is emitted when the subscription is started (handshake success). Channel or channel group mix changes emit PNSubscriptionChangedCategory.
before 4.0.6
PNDisconnectedCategory
PubNub client intentionally disconnected from the real-time updates stream.
before 4.0.6
PNDisconnectedUnexpectedlyCategory
PubNub client unexpectedly disconnected from the real-time updates stream. This status may contain an error field that provides more information about the error.
8.9.0
PNConnectionErrorCategory
PubNub client wasn't able to connect to the real-time updates stream. Returned when the previously started subscribe loop failed, and the client disconnected from real-time data channels. It can happen because of permissions errors or because the network is down. This status may contain an error field that provides more information about the error.
before 4.0.6
PNSubscriptionChangedCategory
The mix of subscribed channels and channel groups has changed. This event returns two arrays: one with all currently subscribed channels and the second with all currently subscribed channel groups.
9.5.0
SDK connection lifecycle

Intermediate states like connecting and reconnecting are now handled internally without emitting specific statuses. For more general information on statuses and reconnection policies, refer to SDK Connection Lifecycle.

Browser-specific statuses​

You can configure the SDK to emit the following additional statuses when the network status changes in the browser environment.

It doesn't matter if enableEventEngine is true or false, the SDK emits the same browser-specific statuses.

StatusDescription
PNNetworkDownCategory
The internet connection isn't available, or PubNub servers aren't reachable.
PNNetworkUpCategory
The internet connection is available, and PubNub servers are reachable.
Handling 403 errors in subscribe

If you receive 403 (Access Denied) errors during subscription, they appear as PNConnectionErrorCategory with PNAccessDeniedCategory in the nested error field. Verify your Access Manager token has read permissions for the subscribed channels.

Migrating to the new subscription loop​

When to migrate

These instructions only apply if you haven't yet enabled the new subscription loop.

When the SDK uses the new subscription loop (enableEventEngine: true), the only user-facing change is subscription status events.

Messages, presence, and all other APIs work exactly as before. Only the status categories emitted by the subscription have changed. There are fewer categories, richer error detail, and no more ambiguity between first-connect and reconnect.

No action is required if your application doesn't inspect status categories in its listener. If you rely on PNConnectedCategory to mean "channels or groups were added or removed," read on.

Key status change: PNConnectedCategory​

Before (legacy)After (new subscription loop)
PNConnectedCategory fired on every subscription change (adding or removing channels or channel groups).
PNConnectedCategory is emitted only when the subscription is started. Subsequent channel mix changes emit PNSubscriptionChangedCategory instead.
Update listener logic if you rely on connection status

If your application treats PNConnectedCategory as "subscription list changed" or runs logic on every subscribe/unsubscribe, switch that logic to PNSubscriptionChangedCategory. Use PNConnectedCategory only for the initial subscription start.

New statuses​

StatusDescription
PNSubscriptionChangedCategory
Fires when channels or channel groups are added or removed after the initial subscription. Returns arrays of all currently subscribed channels and groups.
PNDisconnectedUnexpectedlyCategory
The client lost its real-time connection unexpectedly. Inspect the error field for root-cause details.
PNConnectionErrorCategory
The client was unable to establish or re-establish the real-time connection. The error field contains specifics (e.g. 403, timeout, network failure).

Listener migration example​

pubnub.addListener({
  status: (statusEvent) => {
    if (statusEvent.category === 'PNConnectedCategory') {
      // This ran on first connect AND every time channels/groups were added or removed
      console.log('Subscription updated:', statusEvent.affectedChannels, statusEvent.affectedChannelGroups);
    }
  }
});

Migration steps:

  1. Set enableEventEngine to true in your config.

  2. If you inspect statusEvent.category, add handling for PNSubscriptionChangedCategory for channel/group add/remove; reserve PNConnectedCategory for the initial subscription start only.

  3. Optionally handle PNDisconnectedUnexpectedlyCategory and PNConnectionErrorCategory and use their error field for diagnostics.

  4. Test your application to ensure it handles the new statuses correctly.

Last updated on
On this page