diff --git a/lib/browser/mqtt.ts b/lib/browser/mqtt.ts
index 63ed272da..ca515ff20 100644
--- a/lib/browser/mqtt.ts
+++ b/lib/browser/mqtt.ts
@@ -12,6 +12,7 @@
  * @mergeTarget
  */
 
+import type { Mqtt5Client } from "./mqtt5";
 import * as mqtt from "mqtt";
 import * as WebsocketUtils from "./ws";
 import * as auth from "./auth";
@@ -203,6 +204,11 @@ export interface MqttConnectionConfig {
 }
 
 /**
+ * @deprecated We strongly recommend using {@link Mqtt5Client}
+ * There are no current plans to fully deprecate the MQTT 3.1.1 client but it is highly recommended customers
+ * migrate to the MQTT5 client to access a more robust feature set, clearer error handling, and lifetime
+ * management. More details can be found in the GitHub Repo FAQ
+ * 
  * MQTT client
  *
  * @category MQTT
diff --git a/lib/native/aws_iot.ts b/lib/native/aws_iot.ts
index 9d3d797c3..5100014a4 100644
--- a/lib/native/aws_iot.ts
+++ b/lib/native/aws_iot.ts
@@ -17,6 +17,7 @@ import * as platform from '../common/platform';
 import { HttpProxyOptions } from "./http";
 import { WebsocketOptionsBase } from "../common/auth";
 import { CrtError } from "./error";
+import type { Mqtt5Client } from "./mqtt5";
 
 import {
     aws_sign_request,
@@ -50,6 +51,11 @@ export interface WebsocketConfig extends WebsocketOptionsBase{
 }
 
 /**
+ * @deprecated Please use {@link Mqtt5Client}
+ * The MQTT 3.1.1 client remains fully supported, but migrating to
+ * MQTT 5 gives you a richer feature set, clearer error handling, and
+ * improved lifetime management.
+ * 
  * Builder functions to create a {@link MqttConnectionConfig} which can then be used to create
  * a {@link MqttClientConnection}, configured for use with AWS IoT.
  *
@@ -79,6 +85,11 @@ export class AwsIotMqttConnectionConfigBuilder {
     }
 
     /**
+     * @deprecated We strongly recommend using {@link Mqtt5Client}.  
+     * There are no current plans to fully deprecate the MQTT 3.1.1 client but it is highly recommended customers
+     * migrate to the MQTT5 client to access a more robust feature set, clearer error handling, and lifetime
+     * management. More details can be found in the GitHub Repo FAQ
+     * 
      * Create a new builder with mTLS file paths
      * @param cert_path - Path to certificate, in PEM format
      * @param key_path - Path to private key, in PEM format
@@ -95,6 +106,11 @@ export class AwsIotMqttConnectionConfigBuilder {
     }
 
     /**
+     * @deprecated We strongly recommend using {@link Mqtt5Client}.  
+     * There are no current plans to fully deprecate the MQTT 3.1.1 client but it is highly recommended customers
+     * migrate to the MQTT5 client to access a more robust feature set, clearer error handling, and lifetime
+     * management. More details can be found in the GitHub Repo FAQ
+     * 
      * Create a new builder with mTLS cert pair in memory
      * @param cert - Certificate, in PEM format
      * @param private_key - Private key, in PEM format
@@ -111,6 +127,11 @@ export class AwsIotMqttConnectionConfigBuilder {
     }
 
     /**
+     * @deprecated We strongly recommend using {@link Mqtt5Client}.  
+     * There are no current plans to fully deprecate the MQTT 3.1.1 client but it is highly recommended customers
+     * migrate to the MQTT5 client to access a more robust feature set, clearer error handling, and lifetime
+     * management. More details can be found in the GitHub Repo FAQ
+     * 
      * Create a new builder with mTLS using a PKCS#11 library for private key operations.
      *
      * NOTE: This configuration only works on Unix devices.
@@ -128,6 +149,11 @@ export class AwsIotMqttConnectionConfigBuilder {
     }
 
     /**
+     * @deprecated We strongly recommend using {@link Mqtt5Client}.  
+     * There are no current plans to fully deprecate the MQTT 3.1.1 client but it is highly recommended customers
+     * migrate to the MQTT5 client to access a more robust feature set, clearer error handling, and lifetime
+     * management. More details can be found in the GitHub Repo FAQ
+     * 
      * Create a new builder with mTLS using a PKCS#12 file for private key operations.
      *
      * Note: This configuration only works on MacOS devices.
@@ -147,6 +173,11 @@ export class AwsIotMqttConnectionConfigBuilder {
     }
 
     /**
+     * @deprecated We strongly recommend using {@link Mqtt5Client}.  
+     * There are no current plans to fully deprecate the MQTT 3.1.1 client but it is highly recommended customers
+     * migrate to the MQTT5 client to access a more robust feature set, clearer error handling, and lifetime
+     * management. More details can be found in the GitHub Repo FAQ
+     * 
      * Create a new builder with mTLS using a certificate in a Windows certificate store.
      *
      * NOTE: This configuration only works on Windows devices.
@@ -166,6 +197,11 @@ export class AwsIotMqttConnectionConfigBuilder {
     }
 
     /**
+     * @deprecated We strongly recommend using {@link Mqtt5Client}.  
+     * There are no current plans to fully deprecate the MQTT 3.1.1 client but it is highly recommended customers
+     * migrate to the MQTT5 client to access a more robust feature set, clearer error handling, and lifetime
+     * management. More details can be found in the GitHub Repo FAQ
+     * 
      * Creates a new builder with default Tls options. This requires setting the connection details manually.
      */
     static new_default_builder() {
diff --git a/lib/native/mqtt.ts b/lib/native/mqtt.ts
index b34227198..0060f0967 100644
--- a/lib/native/mqtt.ts
+++ b/lib/native/mqtt.ts
@@ -12,6 +12,7 @@
  * @mergeTarget
  */
 
+import type { Mqtt5Client } from "./mqtt5";
 import crt_native from './binding';
 import { NativeResource, NativeResourceMixin } from "./native_resource";
 import { BufferedEventEmitter } from '../common/event';
@@ -96,6 +97,11 @@ export type MqttConnectionFailure = (callback_data: OnConnectionFailedResult) =>
 export type MqttConnectionClosed = (callback_data: OnConnectionClosedResult) => void;
 
 /**
+ * @deprecated We strongly recommend using {@link Mqtt5Client}.  
+ * There are no current plans to fully deprecate the MQTT 3.1.1 client but it is highly recommended customers
+ * migrate to the MQTT5 client to access a more robust feature set, clearer error handling, and lifetime
+ * management. More details can be found in the GitHub Repo FAQ
+ * 
  * MQTT client
  *
  * @category MQTT