AblyDocs

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

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

Copied!

On CentOS/RHEL:

sudo yum update ca-certificates

Copied!

On macOS:

brew install ca-certificates
# Or update existing:
brew upgrade ca-certificates

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