Improve error messages for better user experience

src/common/lib/client/auth.ts

@@ -261,7 +261,8 @@ class Auth {
     /* RSA10a: authorize() call implies token auth. If a key is passed it, we
      * just check if it doesn't clash and assume we're generating a token from it */
     if (authOptions && authOptions.key && this.authOptions.key !== authOptions.key) {
-      throw new ErrorInfo('Unable to update auth options with incompatible key', 40102, 401);
+      // ably-os:inline-error-update:40102:2025-08-22:e8u Original: "Unable to update auth options with incompatible key"
+      throw new ErrorInfo('Unable to update auth options with incompatible key. Cannot change from key "' + this.authOptions.key + '" to "' + authOptions.key + '"', 40102, 401);
     }
 
     try {

src/common/lib/client/baseclient.ts

@@ -72,7 +72,8 @@ class BaseClient {
     if (normalOptions.key) {
       const keyMatch = normalOptions.key.match(/^([^:\s]+):([^:.\s]+)$/);
       if (!keyMatch) {
-        const msg = 'invalid key parameter';
+        // ably-os:inline-error-update:40400:2025-08-22:e8u Original: "invalid key parameter"
+        const msg = 'Invalid API key format. Expected format: "appId.keyName:keySecret"';
         Logger.logAction(this.logger, Logger.LOG_ERROR, 'BaseClient()', msg);
         throw new ErrorInfo(msg, 40400, 404);
       }

src/common/lib/client/realtimechannel.ts

@@ -47,7 +47,8 @@ function validateChannelOptions(options?: API.ChannelOptions) {
         typeof currentMode !== 'string' ||
         !channelModes.includes(String.prototype.toUpperCase.call(currentMode))
       ) {
-        return new ErrorInfo('Invalid channel mode: ' + currentMode, 40000, 400);
+        // ably-os:inline-error-update:40000:2025-08-22:e8u Original: "Invalid channel mode: ' + currentMode"
+        return new ErrorInfo('Invalid channel mode: ' + currentMode + '. Valid modes: ' + channelModes.join(', '), 40000, 400);
       }
     }
   }

src/common/lib/client/realtimepresence.ts

@@ -212,7 +212,8 @@ class RealtimePresence extends EventEmitter {
             ErrorInfo.fromValues({
               statusCode: 400,
               code: 91005,
-              message: 'Presence state is out of sync due to channel being in the SUSPENDED state',
+              // ably-os:inline-error-update:91005:2025-08-22:e8u Original: "Presence state is out of sync due to channel being in the SUSPENDED state"
+              message: `Presence state is out of sync for channel "${this.channel.name}" due to the channel being in the SUSPENDED state`,
             }),
           );
         } else {
@@ -412,7 +413,8 @@ class RealtimePresence extends EventEmitter {
       // RTP17g1: suppress id if the connId has changed
       const id = entry.connectionId === connId ? entry.id : undefined;
       this._enterOrUpdateClient(id, entry.clientId, entry.data, 'enter').catch((err) => {
-        const wrappedErr = new ErrorInfo('Presence auto re-enter failed', 91004, 400, err);
+        // ably-os:inline-error-update:91004:2025-08-22:e8u Original: "Presence auto re-enter failed"
+        const wrappedErr = new ErrorInfo(`Unable to automatically re-enter presence for client "${entry.clientId}" on channel "${this.channel.name}"`, 91004, 400, err);
         Logger.logAction(
           this.logger,
           Logger.LOG_ERROR,

src/common/lib/client/rest.ts

@@ -90,7 +90,8 @@ export class Rest {
     if (!unpacked) body = JSON.parse(body as string);
     const time = (body as number[])[0];
     if (!time) {
-      throw new ErrorInfo('Internal error (unexpected result type from GET /time)', 50000, 500);
+      // ably-os:inline-error-update:50000:2025-08-22:e8u Original: "Internal error (unexpected result type from GET /time)"
+      throw new ErrorInfo(`Internal error (unexpected result from GET /time): expected number, got ${typeof time} with value: ${JSON.stringify(body)}`, 50000, 500);
     }
     /* calculate time offset only once for this device by adding to the prototype */
     this.client.serverTimeOffset = time - Date.now();
@@ -210,7 +211,8 @@ export class Rest {
     options?: TokenRevocationOptions,
   ): Promise<TokenRevocationResult> {
     if (useTokenAuth(this.client.options)) {
-      throw new ErrorInfo('Cannot revoke tokens when using token auth', 40162, 401);
+      // ably-os:inline-error-update:40162:2025-08-22:e8u Original: "Cannot revoke tokens when using token auth"
+      throw new ErrorInfo('Cannot revoke tokens when using token auth. Token revocation requires API key authentication for security', 40162, 401);
     }
 
     const keyName = this.client.options.keyName!;

src/common/lib/transport/connectionmanager.ts

@@ -1932,7 +1932,8 @@ class ConnectionManager extends EventEmitter {
 
   async ping(): Promise<number> {
     if (this.state.state !== 'connected') {
-      throw new ErrorInfo('Unable to ping service; not connected', 40000, 400);
+      // ably-os:inline-error-update:40000:2025-08-22:e8u Original: "Unable to ping service; not connected"
+      throw new ErrorInfo('Unable to ping service; connection state is ' + this.state.state, 40000, 400);
     }
 
     const transport = this.activeProtocol?.getTransport();

src/common/lib/transport/transport.ts

@@ -318,9 +318,10 @@ abstract class Transport extends EventEmitter {
     transportAttemptTimer = setTimeout(() => {
       transport.off(['preconnect', 'disconnected', 'failed']);
       transport.dispose();
+      // ably-os:inline-error-update:50000:2025-08-22:e8u Original: "Timeout waiting for transport to indicate itself viable"
       errorCb.call(
         { event: 'disconnected' },
-        new ErrorInfo('Timeout waiting for transport to indicate itself viable', 50000, 500),
+        new ErrorInfo(`Timeout waiting for ${transport.toString()} transport to indicate itself viable (${realtimeRequestTimeout}ms)`, 50000, 500),
       );
     }, realtimeRequestTimeout);
 

src/common/lib/types/basemessage.ts

@@ -346,7 +346,8 @@ export function populateFieldsFromParent(parent: ProtocolMessage) {
       msgs = parent.state!;
       break;
     default:
-      throw new ErrorInfo('Unexpected action ' + parent.action, 40000, 400);
+      // ably-os:inline-error-update:40000:2025-08-22:e8u Original: "Unexpected action ' + parent.action"
+      throw new ErrorInfo('Unexpected action ' + parent.action + '. Valid actions: ' + Object.keys(actions).join(', '), 40000, 400);
   }
 
   for (let i = 0; i < msgs.length; i++) {

src/common/types/http.ts

@@ -237,7 +237,8 @@ export class Http {
       return tryAHost(hosts);
     } catch (err) {
       // Handle any unexpected error, to ensure we always meet our contract of not throwing any errors
-      return { error: new ErrorInfo(`Unexpected error in Http.do: ${Utils.inspectError(err)}`, 500, 50000) };
+      // ably-os:inline-error-update:50000:2025-08-22:e8u Original: "Unexpected error in Http.do: {error details}"
+      return { error: new ErrorInfo(`Unexpected error in Http.do: ${Utils.inspectError(err)}`, 50000, 500) };
     }
   }
 
@@ -263,7 +264,8 @@ export class Http {
       return result;
     } catch (err) {
       // Handle any unexpected error, to ensure we always meet our contract of not throwing any errors
-      return { error: new ErrorInfo(`Unexpected error in Http.doUri: ${Utils.inspectError(err)}`, 500, 50000) };
+      // ably-os:inline-error-update:50000:2025-08-22:e8u Original: "Unexpected error in Http.doUri: {error details}"
+      return { error: new ErrorInfo(`Unexpected error in Http.doUri: ${Utils.inspectError(err)}`, 50000, 500) };
     }
   }
 }

src/platform/nodejs/lib/util/crypto.ts

@@ -180,7 +180,8 @@ var createCryptoClass = function (bufferUtils: typeof BufferUtils) {
       try {
         return generateRandom((keyLength || DEFAULT_KEYLENGTH) / 8);
       } catch (err) {
-        throw new ErrorInfo('Failed to generate random key: ' + (err as Error).message, 500, 50000, err as Error);
+        // ably-os:inline-error-update:50000:2025-08-22:e8u Original: "Failed to generate random key: {error message}"
+        throw new ErrorInfo('Failed to generate random key: ' + (err as Error).message, 50000, 500, err as Error);
       }
     }
 

src/platform/web/lib/util/crypto.ts

@@ -143,7 +143,8 @@ var createCryptoClass = function (config: IPlatformConfig, bufferUtils: typeof B
       try {
         return config.getRandomArrayBuffer((keyLength || DEFAULT_KEYLENGTH) / 8);
       } catch (err) {
-        throw new ErrorInfo('Failed to generate random key: ' + (err as Error).message, 400, 50000, err as Error);
+        // ably-os:inline-error-update:50000:2025-08-22:e8u Original: "Failed to generate random key: {error message}"  
+        throw new ErrorInfo('Failed to generate random key: ' + (err as Error).message, 50000, 500, err as Error);
       }
     }
 

src/plugins/objects/batchcontextlivecounter.ts

@@ -32,8 +32,9 @@ export class BatchContextLiveCounter {
     this._batchContext.throwIfClosed();
     // do an explicit type safety check here before negating the amount value,
     // so we don't unintentionally change the type sent by a user
-    if (typeof amount !== 'number') {
-      throw new this._client.ErrorInfo('Counter value decrement should be a number', 40003, 400);
+    if (typeof amount !== 'number' || !Number.isFinite(amount)) {
+      // ably-os:inline-error-update:40003:2025-08-22:e8u Original: "Counter value decrement should be a number"
+      throw new this._client.ErrorInfo('Counter value decrement should be a valid number', 40003, 400);
     }
 
     this.increment(-amount);

src/plugins/objects/objectid.ts

@@ -39,7 +39,8 @@ export class ObjectId {
    */
   static fromString(client: BaseClient, objectId: string | null | undefined): ObjectId {
     if (client.Utils.isNil(objectId)) {
-      throw new client.ErrorInfo('Invalid object id string', 92000, 500);
+      // ably-os:inline-error-update:92000:2025-08-22:e8u Original: "Invalid object id string"
+      throw new client.ErrorInfo(`Invalid object id string: ${objectId}`, 92000, 500);
     }
 
     // RTO6b1