Debugging

Errors can occur in various scenarios when using Ably, such as invalid inputs in requests, authentication issues, or connection problems caused by network disruptions. Proper debugging is essential for building a reliable application and troubleshooting.

You can debug issues in your Ably-supported app using the following:

• Set up a custom log handler to capture and manage errors in a way that suits your requirements.
• Meta channels allow you to monitor errors that might not otherwise be visible to clients, providing additional insights into issues.
• The Dev console in your Ably dashboard is a quick and easy way to inspect errors and events, especially during development or debugging.

Monitoring best practices

Use SDK mechanisms for error detection

Ably SDKs provide built-in mechanisms to notify you when errors occur:

• Connection state changes - The connection will emit events when it changes state. If it enters the disconnected or failed state, the state change will include a reason explaining why. In the disconnected state, it will automatically retry after 15 seconds.
• Channel state changes - Channel state works similarly, with different states and automatic retry behavior.
• Client library logs - ERROR level logs can be accessed programmatically using a custom log handler.

Avoid monitoring HTTP status codes

Strongly recommended against monitoring HTTP status codes of individual requests to detect problems. An HTTP request with a non-2xx response does not necessarily indicate a problem.

There are many possible reasons individual HTTP requests may return error status codes, especially with imperfect network connections, and only a small fraction represent actual problems. For example:

• When a token expires and cannot complete online reauth in time, a comet receive stream will close with a 401 status code and error code 40142. This is expected behavior that triggers the library to obtain a new token and resume the connection.
• Many actual problems won't show up as non-2xx HTTP requests (e.g., errors sent as protocol messages down a WebSocket).

The Ably protocol was designed to use semantically appropriate status codes for each response, rather than avoiding non-2xx responses except for genuine unexpected conditions.

Recommended approach: Use the built-in SDK mechanisms, particularly connection state changes and channel state changes, for reliable error detection and monitoring.

SSL certificate issues

Common SSL certificate errors

If you encounter SSL certificate errors when connecting to Ably, you may see errors such as:

cURL error: SSL certificate problem: self signed certificate in certificate chain
SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed
SSL: CERTIFICATE_VERIFY_FAILED certificate verify failed: unable to get local issuer certificate
Copy
Copied!

These errors are usually caused by out-of-date root certificates on your server or local machine.

Root cause

SSL certificate verification failures typically occur when:

• Your system's root certificate authority (CA) certificates are outdated
• The certificate chain cannot be properly verified
• Your system lacks the necessary intermediate certificates

Solutions

Update root certificates

The most common solution is to update your system's root certificates:

On Ubuntu/Debian:

sudo apt-get update && sudo apt-get install ca-certificates
Copy
Copied!

On CentOS/RHEL:

sudo yum update ca-certificates
Copy
Copied!

On macOS:

brew install ca-certificates
# Or update existing:
brew upgrade ca-certificates
Copy
Copied!

On Windows: Windows typically updates root certificates through Windows Update. Ensure your system is up to date.

Language-specific solutions

Different programming languages may require additional steps:

PHP: Update your curl.cainfo setting in php.ini or download the latest CA bundle from curl.se

Ruby: Update your Ruby installation or use the certified gem to ensure proper certificate verification

Node.js: Update Node.js to the latest version, which includes updated root certificates

Python: Update the certifi package which provides Mozilla's root certificates

Alternative approaches

If updating root certificates doesn't resolve the issue:

1. Check your firewall/proxy: Corporate networks may intercept SSL connections
2. Verify system time: Ensure your system clock is accurate, as certificate validation depends on correct time
3. Test with curl: Use curl -I https://rest.ably.io to test SSL connectivity directly

If you continue experiencing SSL certificate issues after trying these solutions, contact Ably support with details about your platform, programming language, and the specific error messages you're seeing.

Error info

All errors returned by Ably are standardized and use the ErrorInfo object:

{
  "code": 40005,
  "statusCode": 400,
  "cause": "Authentication",
  "nonfatal": false,
  "href": "https://help.ably.io/error/40005"
}

The following explains each property of an ErrorInfo object:

• code := Ably-specific numeric code indicating the error type.
• statusCode := An HTTP status code providing broader context, such as 400 for a bad request.
• cause := A brief description of the issue.
• nonfatal := A boolean indicating whether the error is critical.
• href := A direct link to Ably's documentation or for quick troubleshooting references.

Logging

Ably SDKs allow you to customize the function that handles logging. This function is usually set in the options when configuring a client, such as the ClientOptions object for Pub/Sub.

Two separate properties can be set:

• logHandler := Provides a custom function for each line of log output.
• logLevel := The verbosity of the logging output, from silent to trace. In some SDKs this is numeric, and in others string.

The following table explains the logLevel setting for the Ably client, which controls how much logging output is shown. Higher levels include more detailed information:

The following example configures the Ably client to log only error messages using logLevel:1 and processes them with the function logWriteFun():

const ablyClient = new Ably.Realtime({
  key: demokey:*****,
  logHandler: logWriteFunc,
  logLevel: 1 // Errors only
});

The following example is a log output for an Ably client configured to log messages using logLevel:1:

LOG [Level 1]: Ably: ConnectionManager.failQueuedMessages(): failing 1 queued messages, err = [_ErrorInfo: Application Ptz0jg disabled.
(See https://help.ably.io/error/40300 for help.); statusCode=403; code=40300]

Metachannels

Ably provides a set of metachannels that expose internal events from the Ably system. These metachannels are be useful for debugging and monitoring, especially when investigating issues not surfaced directly to clients.

There are two metachannels related to logging:

• [meta]log := Publishes errors that aren't visible to clients, except those related to push notifications.
• [meta]log:push := Similar to [meta]log, but only publishes errors related to the delivery of push notifications.

The following example subscribes to the [meta]log channel:

const channel = realtime.channels.get('[meta]log');
channel.subscribe((msg) => {
  console.log(msg);
});

The following is an example event published to the [meta]log channel as an ErrorInfo object:

{
  "code": 40005,
  "statusCode": 400,
  "cause": "Authentication",
  "nonfatal": false,
  "href": "https://help.ably.io/error/40005"
}

Dev console

The Dev console in your Ably dashboard is a quick and easy way to inspect errors. It provides a live stream of all events in your application, which is especially useful during early-stage development or low-traffic periods when events are easier to track:

• Monitor all live events in your application for detailed insights.
• Test publishing and subscribing to channels to identify and resolve issues with these functions.

Support tickets

If the provided information does not resolve your issue, contact Ably support. When contacting, include details such as your app ID, the error code, and any relevant logs to help troubleshoot.

The following information is essential for effective troubleshooting, include as much of the following information as possible:

• Provide timestamps in UTC format.
• Include complete SDK logs from the time of the failure. Ensure these logs show activity before and after the timeout, as SDKs retry failed requests by default.
• Specify which endpoints were accessed. Mention if you use custom client options, the environment setting, and the failing SDK operation.
• State the SDK/s you use, including the platform and versions.
• Include any stack traces related to the error.
• Indicate whether the issue occurs consistently or was a one-time event.
• Provide details to confirm whether the issue was related to your network or Ably's availability. For example, note whether other internet operations were succeeding simultaneously.
• Include the appID associated with the request.