DOCS
Ask AI

Troubleshoot PubNub request failures

Use this guide to diagnose a PubNub request failure before you contact PubNub Support. Start with the failing operation's code or SDK status category, then capture logs before you retry or escalate. This guide links to the canonical fixes in Connection management and Access Manager.

Find the right starting point​

Check these symptoms one by one, in the order listed, to narrow a vague failure down to a specific place to look. The order rules out the most common causes first. Each item names a symptom and where to look, and the last item sends you to log capture.


  • Every client on the keyset fails the same way. This looks like an outage rather than something in your application. Check PubNub Status for an active incident before you dig further.
  • Access was denied where it wasn't before. Check available permissions to decode the token and confirm what it actually grants. If it expired, refer to Update an expired token. If someone revoked it, or a keyset setting or role changed underneath it, the audit log shows who changed what, and when.
  • The same operation fails after roughly the same delay, every time. That's the shape of a client-side timeout, not a rejection. A timeout can originate anywhere between your application and PubNub: the app, the device, the local network, DNS, the ISP, or PubNub's own network. Enable logging (below) and check whether the request ever left your process. A request that never reaches PubNub fails the same way as one PubNub rejected slowly.
  • You don't recognize the code or the status category. Error codes catalogs the HTTP status codes themselves. The literal category names belong to your SDK, not the platform. Check your own SDK's status events reference next, for example JavaScript or Python. For any other language, refer to Available SDKs to find its copy.
  • None of the above matches. Capture logs before you contact Support, covered next, so the first response you get is a diagnosis rather than a request for more information.

Capture logs before you dig further​

PubNub SDKs share a common set of log levels. PubNub SDK logging is disabled by default. Enable it in your SDK's configuration, then choose a level to control how much detail it captures.

LevelWhen to use
ERRORProduction. Captures failures and exceptions with minimal performance impact.
WARNProduction or staging. Adds deprecated-feature and validation warnings.
INFOStaging. Adds successful initialization and configuration changes.
DEBUGActive development. Adds API parameters and full HTTP request and response details.
TRACEDeep troubleshooting. Adds internal execution flow, including serialization and encryption steps. Generates high volume output.

DEBUG and TRACE can log sensitive data, including API keys, user identifiers, message content, and the full token string from a grantToken call. Both levels log complete request URLs and response bodies, which is where that data comes from. Use them only in development, and never leave either one enabled in production. For the configuration option and any platform-specific logger integration, refer to your SDK's Logging documentation, for example JavaScript or Python.

Before you open a support ticket, reproduce the issue with DEBUG or TRACE enabled and include:

IncludeWhy
SDK initialization and configurationShows the SDK version and the settings that produced the failure.
The full operation sequence leading to the failure, with timestampsLets support correlate your logs with server-side data for the same window.
The exact error message or exceptionDistinguishes a documented code from an SDK-internal exception.
Your platform and runtime versionRules out an environment-specific cause.

Sanitize credentials, tokens, and message content out of the logs before you share them, since DEBUG and TRACE capture exactly the values the warning above names.

SDK troubleshooting and status event references​

Use these links when you need the category names, logging configuration, or troubleshooting advice for a specific SDK.

  • Error codes. The HTTP status codes PubNub's APIs return and what each one means.
  • Connection management. The status categories your SDK reports, and what each means for the subscribe connection.
  • Check available permissions. Decode a token to diagnose a 403 error.
  • Audit log. Confirm whether a keyset setting, role, or key changed before a client started failing.
  • Architectural choices. Decide how your application responds to a failure category as part of its design, not as a patch after the fact.

Was this page useful?

Last updated on