For AI agents: this page in Markdown: https://www.pubnub.com/docs/sdks/javascript/troubleshooting.md. Documentation index: https://www.pubnub.com/llms-full.txt.

Troubleshoot the PubNub JavaScript SDK

Use this page to fix common problems in the PubNub JavaScript SDK by matching what you see in your app to its cause and fix. Status categories such as PNConnectionErrorCategory reach only the status listener that you add on the PubNub client, so add one before you troubleshoot. If your symptom is not listed, go to Get help.

Each entry gives the symptom as its heading, then the cause and the fix. For a decision tree that covers all PubNub SDKs, refer to Troubleshoot PubNub request failures.

Connection​

The PubNub constructor throws a configuration error​

  • Cause: The constructor throws a PubNubError when userId is omitted, is empty or only whitespace, or is set together with uuid. The SDK sends no request first.
  • Fix: Set a unique userId in the configuration when you create the PubNub instance, and set no uuid. Keep the userId unchanged for the lifetime of the user or the device. Refer to Initialization errors.

The subscription fails with PNConnectionErrorCategory​

  • Cause: The client could not establish the connection to the real-time updates stream. Permission errors and a network outage can both cause it. The error field of the status contains the specifics.
  • Fix: Inspect the error field. If it contains PNAccessDeniedCategory (403), follow Access is denied (403). Otherwise, check the network connection. For all categories, refer to Status events.

The client disconnects unexpectedly​

  • Cause: The client lost its real-time connection. The SDK reports it as PNDisconnectedUnexpectedlyCategory, available from version 8.9.0 and when enableEventEngine is true (the default). With the legacy subscription manager (enableEventEngine: false), a lost connection can appear as PNNetworkIssuesCategory. That category means the client could not reach PubNub servers because of a network issue or a proxy.
  • Fix: Read the error field on the status for the root cause. If the app runs in a browser, configure the SDK to emit PNNetworkDownCategory and PNNetworkUpCategory when the network status changes. For how the SDK handles reconnection, refer to SDK Connection Lifecycle.

The status is PNUnknownCategory or PNMalformedResponseCategory​

  • Cause: The client received an unexpected response or hit an error that it could not categorize. Common causes are aborted requests (errorData contains [Error: Aborted]), non-standard HTTP responses from proxies or VPNs, and unhandled HTTP status codes. A 200 response with a body that is not JSON, an empty body, or an HTML page from a proxy also gives PNUnknownCategory, with statusCode 0. In these cases the SDK does not report PNMalformedResponseCategory.
  • Fix: Check the statusCode and errorData fields of the status. If a proxy or VPN sits between your app and PubNub, test without it. Refer to Status events.

Access​

Access is denied (403)​

  • Cause: The authorization key or token does not have the permissions the request needs, because of an Access Manager failure. In a subscribe loop, the 403 appears as PNConnectionErrorCategory with PNAccessDeniedCategory in the nested error field.
  • Fix: If the request is a subscribe, verify that your token has read permissions for the subscribed channels. Check available permissions to decode the token and see what it grants. If the token expired, follow Update an expired token. If someone revoked it, or a keyset setting or role changed, the audit log shows who changed what and when.

Publishing​

Publish fails with Message Too Large​

  • Cause: The message exceeds the size limit. A publish by POST (sendByPost: true) fails with HTTP 413 Request Entity Too Large, and a publish by GET (the default) fails with HTTP 414 Request URI Too Long. The SDK reports both as PNUnknownCategory. PubNub can process messages up to 2 MB in size, but the default message payload is limited to 32 KiB. This includes the channel name and any metadata.
  • Fix: Reduce the payload below the limit. Refer to Publish.

Publish fails with PNBadRequestCategory or PNValidationErrorCategory​

  • Cause: A client without a publishKey, or a call without channel or message, fails before the SDK sends a request. The SDK reports PNValidationErrorCategory with the message Missing 'publishKey', Missing 'channel', or Missing 'message'. PNBadRequestCategory means PubNub answered the request with HTTP 400 because the request is malformed in another way. Refer to Status events.
  • Fix: Set publishKey in the configuration if you did not, and include both channel and message in the call. Refer to Publish.

Receiving​

Logic tied to PNConnectedCategory runs only once after you upgrade​

  • Cause: Since SDK version 11.0.0, enableEventEngine defaults to true. PNConnectedCategory is now emitted only when the subscription starts. Changes to the channel or channel group mix emit PNSubscriptionChangedCategory instead.
  • Fix: If logic ran on every subscribe or unsubscribe, move it to a PNSubscriptionChangedCategory handler. Keep PNConnectedCategory for the initial subscription start. Refer to Migrating to the new subscription loop.

You need messages that were published while the client was not subscribed​

  • Cause: A subscription reports PNConnectedCategory when the client is ready to receive real-time updates. Earlier messages are not part of that stream.
  • Fix: If Message Persistence is enabled on your keyset, fetch earlier messages with Fetch history. You can also pass a cursor with a timetoken when you subscribe, but retrieval with a cursor is a best-effort service and is not guaranteed. Refer to Subscribe. With the legacy subscription manager, PNRequestMessageCountExceededCategory means the client exceeded the configured requestMessageCountThreshold. Enable Message Persistence on the keyset to retrieve what the in-memory cache dropped.

Presence​

Users appear to leave a channel without unsubscribing​

  • Cause: PubNub received no heartbeat or subscribe request from the client within presenceTimeout, so it marked the client offline and emitted a timeout event on the presence channel. PubNub SDKs set presenceTimeout to 300 seconds by default, which is how long PubNub waits without a heartbeat before marking a client offline. A lost network or a stopped app can stop the requests. By default, the client sends no periodic heartbeats between subscribe requests.
  • Fix: If clients stay connected but still time out, set heartbeatInterval so the client sends explicit heartbeats often enough. To detect lost clients sooner, lower presenceTimeout, which also sets heartbeatInterval to half the presence timeout minus one second. Each explicit heartbeat is a billable API call. If you want an immediate leave event instead of a delayed timeout, unsubscribe before the client goes offline. Refer to Configuration and Implicit heartbeats and the presence timeout.

Encryption​

Data uses legacy encryption although cryptoModule is configured​

  • Cause: A cipher key that you pass to a method overrides the configured crypto module for that operation and uses the legacy encryption with 128-bit cipher-key entropy. The cipher key arguments are customCipherKey for encrypt() and decrypt(), and key for encryptFile() and decryptFile().
  • Fix: To use the configured cryptoModule, remove those arguments. The module uses AES-256-CBC when you configure PubNub.CryptoModule.aesCbcCryptoModule. For partial encryption scenarios, configure a separate cryptoModule instance. Refer to CryptoModule configuration.

Get help​

You need more detail than the status gives you​

  • Cause: PubNub SDK logging is disabled by default. The default level is LogLevel.None.
  • Fix: Set logLevel to PubNub.LogLevel.Debug or PubNub.LogLevel.Trace when you create the instance, then reproduce the issue. Refer to Logging.

You need to contact support​

  • Fix: Reproduce the issue with LogLevel.Debug or LogLevel.Trace, copy the console output, and send it to support@pubnub.com. Remove credentials, tokens, and message content from the output first, because these levels can log sensitive data, and do not leave either level enabled in production. Refer to Sensitive data in logs.

You see an unfamiliar status category or HTTP code​

Was this page useful?

Last updated on