diff --git a/src/common/lib/util/defaults.ts b/src/common/lib/util/defaults.ts
index 03810b673f..85fd16c91c 100644
--- a/src/common/lib/util/defaults.ts
+++ b/src/common/lib/util/defaults.ts
@@ -195,6 +195,12 @@ export function normaliseOptions(options: DeprecatedClientOptions): NormalisedCl
     Logger.deprecated('queueEvents', 'queueMessages');
     options.queueMessages = options.queueEvents;
   }
+  if (options.headers) {
+    Logger.deprecatedWithMsg(
+      'the `headers` client option',
+      '' /* there is no replacement; see DeprecatedClientOptions.headers */
+    );
+  }
 
   if (options.fallbackHostsUseDefault) {
     /* fallbackHostsUseDefault and fallbackHosts are mutually exclusive as per TO3k7 */
diff --git a/src/common/types/ClientOptions.ts b/src/common/types/ClientOptions.ts
index 2f9e33df14..fe9e97eaad 100644
--- a/src/common/types/ClientOptions.ts
+++ b/src/common/types/ClientOptions.ts
@@ -19,6 +19,9 @@ export type DeprecatedClientOptions = Modify<
     wsHost?: string;
     queueEvents?: boolean;
     promises?: boolean;
+    /**
+     * This option dates back to the initial commit of the repo but was never in the specification and sounds like nobody is depending on it; Paddy said we can remove in v2 (see https://ably-real-time.slack.com/archives/CURL4U2FP/p1709909310332169?thread_ts=1709908997.753599&cid=CURL4U2FP)
+     */
     headers?: Record<string, string>;
   }
 >;