diff --git a/app/js_error_event.html b/app/js_error_event.html
index a39cb604..05b3ed21 100644
--- a/app/js_error_event.html
+++ b/app/js_error_event.html
@@ -54,6 +54,13 @@
                 cwr('recordError', new Error('My error message'));
             }
 
+            function recordCaughtErrorWithMetadata() {
+                cwr('recordError', {
+                    error: new Error('My error message'),
+                    metadata: { traceId: 'trace-1' }
+                });
+            }
+
             function disable() {
                 cwr('disable');
             }
@@ -96,6 +103,12 @@
         <button id="recordCaughtError" onclick="recordCaughtError()">
             Record caught error
         </button>
+        <button
+            id="recordCaughtErrorWithMetadata"
+            onclick="recordCaughtErrorWithMetadata()"
+        >
+            Record caught error with metadata
+        </button>
         <button id="resizeObserverLoopError" onclick="throwObserverLoopError()">
             Throw ResizeObserverLoopError
         </button>
diff --git a/docs/cdn_commands.md b/docs/cdn_commands.md
index 27ceff5b..fd27b823 100644
--- a/docs/cdn_commands.md
+++ b/docs/cdn_commands.md
@@ -10,6 +10,7 @@ Quick link:
 <script>
     cwr('recordPageView', '/home');
     cwr('recordError', e);
+    cwr('recordError', { error: e, metadata: { traceId: 'abc' } });
     cwr('recordEvent', { type: 'my_event', data: { k: 'v' } });
     cwr('recordEvent', {
         type: 'my_event',
diff --git a/docs/reference/api.md b/docs/reference/api.md
index 7aedaef3..bd17263a 100644
--- a/docs/reference/api.md
+++ b/docs/reference/api.md
@@ -31,7 +31,7 @@ Each row shows the NPM method and the equivalent CDN command.
 | Command | NPM | CDN | Description |
 | --- | --- | --- | --- |
 | **recordPageView** | `awsRum.recordPageView('/home')` | `cwr('recordPageView', '/home')` | Record a page view. Accepts a string (page ID) or a `PageView` object. See [PageView](#pageview). |
-| **recordError** | `awsRum.recordError(e)` | `cwr('recordError', e)` | Record a caught error. Accepts `Error`, `ErrorEvent`, or string. |
+| **recordError** | `awsRum.recordError(e)` <br> `awsRum.recordError(e, { traceId: 'abc' })` | `cwr('recordError', e)` <br> `cwr('recordError', { error, metadata })` | Record a caught error. Accepts `Error`, `ErrorEvent`, or string. The optional 2nd arg attaches per-call metadata, same rules and precedence as [`recordEvent` metadata](#metadata-precedence). On the CDN, an object literal with own `error` and `metadata` keys is read as an envelope; every other payload is recorded as the error itself. |
 | **recordEvent** | `awsRum.recordEvent('type', { ... }, { tier: 'beta' })` | `cwr('recordEvent', { type, data, metadata })` | Record a custom event. The optional 3rd arg attaches per-call metadata (highest precedence). See [Event](#event). ⚠️ AppMonitor must have custom events enabled. |
 | **addSessionAttributes** | `awsRum.addSessionAttributes({ appVersion: '1.3.8' })` | `cwr('addSessionAttributes', { appVersion: '1.3.8' })` | Add metadata attributes to every event in the current session. See [MetadataAttributes](../configuration.md#metadataattributes). |
 | **setEventMetadataHook** | `awsRum.setEventMetadataHook((type, data, ctx) => ({ route: location.pathname }))` | _(NPM only — hooks are functions)_ | Register a function that decorates every recorded event's metadata. The hook receives `(eventType, eventData, currentMetadata)` and returns an `EventMetadata` object. Replaces any previously set hook. Manual metadata passed to `recordEvent` always wins. If the hook throws, its output is dropped for that event and the SDK logs a warning. |
@@ -117,7 +117,7 @@ Per-event metadata is composed of three layers, applied in order from lowest to
 
 1. **Page attributes** — set via `recordPageView({ pageAttributes: ... })`.
 2. **Hook output** — set via `setEventMetadataHook(fn)`. Overrides page attributes for non-reserved keys.
-3. **Manual metadata** — passed as the 3rd argument to `recordEvent`. Overrides hook output.
+3. **Manual metadata** — passed as the 3rd argument to `recordEvent` or the 2nd argument to `recordError`. Overrides hook output.
 
 Session-level metadata travels in the request-level `Metadata` field, separate from per-event metadata. Within session-level metadata, precedence (lowest → highest) is:
 
diff --git a/packages/core/__tests__/plugins/event-plugins/JsErrorPlugin.test.ts b/packages/core/__tests__/plugins/event-plugins/JsErrorPlugin.test.ts
index a82d0b69..72a6f978 100644
--- a/packages/core/__tests__/plugins/event-plugins/JsErrorPlugin.test.ts
+++ b/packages/core/__tests__/plugins/event-plugins/JsErrorPlugin.test.ts
@@ -427,6 +427,74 @@ describe('JsErrorPlugin tests', () => {
         );
     });
 
+    test('when the application records an error with metadata then the metadata is recorded on the error event', async () => {
+        // Init
+        const plugin: JsErrorPlugin = new JsErrorPlugin();
+
+        // Run
+        plugin.load(context);
+        plugin.record(new Error('Something went wrong!'), {
+            traceId: 'trace-1',
+            component: 'PaymentForm'
+        });
+        plugin.disable();
+
+        // Assert
+        expect(record).toHaveBeenCalledTimes(1);
+        expect(record.mock.calls[0][0]).toEqual(JS_ERROR_EVENT_TYPE);
+        expect(record.mock.calls[0][1]).toMatchObject({
+            version: '1.0.0',
+            type: 'Error',
+            message: 'Something went wrong!'
+        });
+        expect(record.mock.calls[0][2]).toEqual({
+            traceId: 'trace-1',
+            component: 'PaymentForm'
+        });
+    });
+
+    test('when no metadata is given then no event metadata is recorded', async () => {
+        // Init
+        const plugin: JsErrorPlugin = new JsErrorPlugin();
+
+        // Run
+        plugin.load(context);
+        plugin.record(new Error('Something went wrong!'));
+        plugin.disable();
+
+        // Assert
+        expect(record.mock.calls[0][2]).toBeUndefined();
+    });
+
+    test('when the application records an ErrorEvent with metadata then the error fields are preserved', async () => {
+        // Init
+        const plugin: JsErrorPlugin = new JsErrorPlugin();
+        const errorEvent = new ErrorEvent('error', {
+            colno: 1,
+            error: new Error('Something went wrong!'),
+            filename: 'main.js',
+            lineno: 2
+        });
+
+        // Run
+        plugin.load(context);
+        plugin.record(errorEvent, { traceId: 'trace-1' });
+        plugin.disable();
+
+        // Assert
+        expect(record).toHaveBeenCalledTimes(1);
+        expect(record.mock.calls[0][0]).toEqual(JS_ERROR_EVENT_TYPE);
+        expect(record.mock.calls[0][1]).toMatchObject({
+            version: '1.0.0',
+            type: 'Error',
+            message: 'Something went wrong!',
+            filename: 'main.js',
+            colno: 1,
+            lineno: 2
+        });
+        expect(record.mock.calls[0][2]).toEqual({ traceId: 'trace-1' });
+    });
+
     test('when unhandledrejection error event outputs empty object as reason then message is recorded as undefined', async () => {
         // Init
         const plugin: JsErrorPlugin = new JsErrorPlugin();
diff --git a/packages/core/src/plugins/InternalPlugin.ts b/packages/core/src/plugins/InternalPlugin.ts
index cb7602cd..0dd965f0 100644
--- a/packages/core/src/plugins/InternalPlugin.ts
+++ b/packages/core/src/plugins/InternalPlugin.ts
@@ -1,6 +1,6 @@
 import { RUM_AWS_PREFIX } from './utils/constant';
 import { Plugin } from './Plugin';
-import { InternalPluginContext } from './types';
+import { EventMetadata, InternalPluginContext } from './types';
 
 export abstract class InternalPlugin<UpdateType = unknown>
     implements Plugin<UpdateType>
@@ -23,7 +23,7 @@ export abstract class InternalPlugin<UpdateType = unknown>
         this.context = context;
         this.onload?.();
     }
-    record?<D>(data: D): void;
+    record?(data: any, metadata?: EventMetadata): void;
     update?(updateWith: UpdateType): void;
 
     abstract enable(): void;
diff --git a/packages/core/src/plugins/Plugin.ts b/packages/core/src/plugins/Plugin.ts
index c6d5749b..85f4360e 100644
--- a/packages/core/src/plugins/Plugin.ts
+++ b/packages/core/src/plugins/Plugin.ts
@@ -1,4 +1,4 @@
-import { PluginContext } from './types';
+import { EventMetadata, PluginContext } from './types';
 
 export interface Plugin<UpdateType = unknown> {
     /**
@@ -29,8 +29,9 @@ export interface Plugin<UpdateType = unknown> {
      * Manually record an event.
      *
      * @param data Data that the plugin will use to create an event.
+     * @param metadata Per-call metadata to attach to the recorded event.
      */
-    record?<D>(data: D): void;
+    record?(data: any, metadata?: EventMetadata): void;
 
     /**
      * Update the plugin.
diff --git a/packages/core/src/plugins/PluginManager.ts b/packages/core/src/plugins/PluginManager.ts
index 1ba83a29..ae448ffc 100644
--- a/packages/core/src/plugins/PluginManager.ts
+++ b/packages/core/src/plugins/PluginManager.ts
@@ -1,5 +1,5 @@
 import { Plugin } from './Plugin';
-import { PluginContext } from './types';
+import { EventMetadata, PluginContext } from './types';
 import { InternalPlugin } from './InternalPlugin';
 import { InternalLogger } from '../utils/InternalLogger';
 
@@ -81,11 +81,12 @@ export class PluginManager {
      *
      * @param pluginId The unique identifier for the plugin being configured.
      * @param data The data to be recorded by the plugin.
+     * @param metadata Per-call metadata to attach to the recorded event.
      */
-    public record(pluginId: string, data: any): void {
+    public record(pluginId: string, data: any, metadata?: EventMetadata): void {
         const plugin = this.getPlugin(pluginId);
         if (plugin?.record instanceof Function) {
-            plugin.record(data);
+            plugin.record(data, metadata);
         } else {
             throw new Error('AWS RUM Client record: Invalid plugin ID');
         }
diff --git a/packages/core/src/plugins/event-plugins/JsErrorPlugin.ts b/packages/core/src/plugins/event-plugins/JsErrorPlugin.ts
index b0e5eba9..066580ba 100644
--- a/packages/core/src/plugins/event-plugins/JsErrorPlugin.ts
+++ b/packages/core/src/plugins/event-plugins/JsErrorPlugin.ts
@@ -1,6 +1,7 @@
 import { InternalPlugin } from '../InternalPlugin';
 import { JS_ERROR_EVENT_TYPE } from '../utils/constant';
 import { errorEventToJsErrorEvent } from '../utils/js-error-utils';
+import { EventMetadata } from '../types';
 
 export const JS_ERROR_EVENT_PLUGIN_ID = 'js-error';
 
@@ -43,11 +44,14 @@ export class JsErrorPlugin extends InternalPlugin {
         this.enabled = false;
     }
 
-    record(error: any): void {
+    record(error: any, metadata?: EventMetadata): void {
         if (error instanceof ErrorEvent) {
-            this.recordJsErrorEvent(error);
+            this.recordJsErrorEvent(error, metadata);
         } else {
-            this.recordJsErrorEvent({ type: 'error', error } as ErrorEvent);
+            this.recordJsErrorEvent(
+                { type: 'error', error } as ErrorEvent,
+                metadata
+            );
         }
     }
 
@@ -70,10 +74,11 @@ export class JsErrorPlugin extends InternalPlugin {
         }
     };
 
-    private recordJsErrorEvent(error: ErrorEvent) {
+    private recordJsErrorEvent(error: ErrorEvent, metadata?: EventMetadata) {
         this.context?.record(
             JS_ERROR_EVENT_TYPE,
-            errorEventToJsErrorEvent(error, this.config.stackTraceLength)
+            errorEventToJsErrorEvent(error, this.config.stackTraceLength),
+            metadata
         );
     }
 
diff --git a/packages/core/src/plugins/event-plugins/__integ__/JsErrorPlugin.spec.ts b/packages/core/src/plugins/event-plugins/__integ__/JsErrorPlugin.spec.ts
index 91b426b2..2070f683 100644
--- a/packages/core/src/plugins/event-plugins/__integ__/JsErrorPlugin.spec.ts
+++ b/packages/core/src/plugins/event-plugins/__integ__/JsErrorPlugin.spec.ts
@@ -146,6 +146,32 @@ test.describe('JSErrorEvent Plugin', () => {
         expect(eventDetails.message).toContain('My error message');
     });
 
+    test('when the application records a caught error with metadata then the metadata is on the event', async ({
+        page
+    }) => {
+        await page.goto('/js_error_event.html');
+
+        await page.waitForTimeout(300);
+        await page.click('#recordCaughtErrorWithMetadata');
+        await page.click('#dispatch');
+
+        await expect(page.locator('#request_body')).toContainText('BatchId');
+
+        const requestBodyText = await page
+            .locator('#request_body')
+            .textContent();
+        const events = JSON.parse(requestBodyText || '{}').RumEvents.filter(
+            (e: any) => e.type === JS_ERROR_EVENT_TYPE
+        );
+
+        const eventDetails = JSON.parse(events[0].details);
+        const eventMetadata = JSON.parse(events[0].metadata);
+
+        expect(events.length).toBe(1);
+        expect(eventDetails.message).toContain('My error message');
+        expect(eventMetadata.traceId).toBe('trace-1');
+    });
+
     test('when ignore function matches error then the plugin does not record the error', async ({
         page
     }) => {
diff --git a/packages/core/src/sessions/VirtualPageLoadTimer.ts b/packages/core/src/sessions/VirtualPageLoadTimer.ts
index d5b7b5a6..08b4e85c 100644
--- a/packages/core/src/sessions/VirtualPageLoadTimer.ts
+++ b/packages/core/src/sessions/VirtualPageLoadTimer.ts
@@ -58,8 +58,10 @@ export class VirtualPageLoadTimer extends MonkeyPatched<
 
     private config: Config;
     private pageManager: PageManager;
+    // Not named `record`: MonkeyPatched inherits an optional public `record` from InternalPlugin,
+    // and a private field of the same name is an illegal override.
     // @ts-ignore
-    private readonly record: RecordEvent;
+    private readonly recordEvent: RecordEvent;
 
     constructor(pageManager: PageManager, config: Config, record: RecordEvent) {
         super('virtual-page-load-timer');
@@ -75,7 +77,7 @@ export class VirtualPageLoadTimer extends MonkeyPatched<
 
         this.config = config;
         this.pageManager = pageManager;
-        this.record = record;
+        this.recordEvent = record;
         this.enable();
 
         // Start tracking the timestamps
@@ -275,8 +277,8 @@ export class VirtualPageLoadTimer extends MonkeyPatched<
             startTime: page.start,
             duration: this.latestEndTime - page.start
         };
-        if (this.record) {
-            this.record(
+        if (this.recordEvent) {
+            this.recordEvent(
                 PERFORMANCE_NAVIGATION_EVENT_TYPE,
                 virtualPageNavigationEvent
             );
diff --git a/packages/slim/__tests__/CommandQueue.test.ts b/packages/slim/__tests__/CommandQueue.test.ts
index af47b95d..a5b8783d 100644
--- a/packages/slim/__tests__/CommandQueue.test.ts
+++ b/packages/slim/__tests__/CommandQueue.test.ts
@@ -305,4 +305,66 @@ describe('Slim CommandQueue tests', () => {
         await cq.push({ c: 'startSession', p: null });
         expect(startSession).not.toHaveBeenCalled();
     });
+
+    test('recordError forwards a bare error', async () => {
+        const cq = new CommandQueue();
+        await cq.init(createAwsRumInit());
+        const error = new Error('test');
+        await cq.push({ c: 'recordError', p: error });
+        expect(recordError).toHaveBeenCalledWith(error);
+    });
+
+    test('recordError forwards metadata from an envelope payload', async () => {
+        const cq = new CommandQueue();
+        await cq.init(createAwsRumInit());
+        const error = new Error('test');
+        await cq.push({
+            c: 'recordError',
+            p: { error, metadata: { traceId: 'trace-1' } }
+        });
+        expect(recordError).toHaveBeenCalledWith(error, {
+            traceId: 'trace-1'
+        });
+    });
+
+    test('recordError treats an error-shaped object without metadata as the error', async () => {
+        const cq = new CommandQueue();
+        await cq.init(createAwsRumInit());
+        const thrown = { error: 'inner', message: 'real error message' };
+        await cq.push({ c: 'recordError', p: thrown });
+        expect(recordError).toHaveBeenCalledWith(thrown);
+    });
+
+    test('recordError treats a thrown Error carrying both envelope keys as the error', async () => {
+        const cq = new CommandQueue();
+        await cq.init(createAwsRumInit());
+        const thrown = Object.assign(new Error('real error message'), {
+            error: 'inner',
+            metadata: { fromError: true }
+        });
+        await cq.push({ c: 'recordError', p: thrown });
+        expect(recordError).toHaveBeenCalledWith(thrown);
+    });
+
+    test('recordError does not treat an inherited metadata key as an envelope', async () => {
+        const cq = new CommandQueue();
+        await cq.init(createAwsRumInit());
+        class ThrownError extends Error {}
+        (ThrownError.prototype as any).error = 'inner';
+        (ThrownError.prototype as any).metadata = { fromProto: true };
+        const thrown = new ThrownError('real error message');
+        await cq.push({ c: 'recordError', p: thrown });
+        expect(recordError).toHaveBeenCalledWith(thrown);
+    });
+
+    test('recordError rejects non-object metadata', async () => {
+        const cq = new CommandQueue();
+        await cq.init(createAwsRumInit());
+        await expect(
+            cq.push({
+                c: 'recordError',
+                p: { error: new Error('test'), metadata: 'oops' }
+            })
+        ).rejects.toThrow('IncorrectParametersException');
+    });
 });
diff --git a/packages/slim/__tests__/orchestration/Orchestration.test.ts b/packages/slim/__tests__/orchestration/Orchestration.test.ts
index e70f73bd..a3d17519 100644
--- a/packages/slim/__tests__/orchestration/Orchestration.test.ts
+++ b/packages/slim/__tests__/orchestration/Orchestration.test.ts
@@ -231,7 +231,20 @@ describe('Slim Orchestration tests', () => {
         orch.recordError(error);
         expect(pluginRecord).toHaveBeenCalledWith(
             'com.amazonaws.rum.js-error',
-            error
+            error,
+            undefined
+        );
+    });
+
+    test('recordError forwards metadata to pluginManager', async () => {
+        const orch = new Orchestration('a', 'c', 'us-east-1', {});
+        const error = new Error('test');
+        const metadata = { traceId: 'trace-1' };
+        orch.recordError(error, metadata);
+        expect(pluginRecord).toHaveBeenCalledWith(
+            'com.amazonaws.rum.js-error',
+            error,
+            metadata
         );
     });
 
diff --git a/packages/slim/src/CommandQueue.ts b/packages/slim/src/CommandQueue.ts
index c41bc5ca..9fc579ad 100644
--- a/packages/slim/src/CommandQueue.ts
+++ b/packages/slim/src/CommandQueue.ts
@@ -24,6 +24,21 @@ export type AwsRumClientInit = {
     u?: string;
 };
 
+const isPlainObject = (value: any): boolean =>
+    typeof value === 'object' && value !== null && !Array.isArray(value);
+
+// The snippet forwards a single payload, so recordError's optional metadata argument arrives as an
+// envelope: cwr('recordError', { error, metadata }). Only an object literal carrying both own keys
+// is an envelope, so a thrown Error, ErrorEvent or any other class instance is still recorded as
+// the error itself.
+const isRecordErrorEnvelope = (
+    payload: any
+): payload is { error: any; metadata: any } =>
+    isPlainObject(payload) &&
+    Object.getPrototypeOf(payload) === Object.prototype &&
+    Object.prototype.hasOwnProperty.call(payload, 'error') &&
+    Object.prototype.hasOwnProperty.call(payload, 'metadata');
+
 export class CommandQueue {
     protected orchestration!: Orchestration;
 
@@ -35,7 +50,14 @@ export class CommandQueue {
             this.orchestration.recordPageView(payload);
         },
         recordError: (payload: any): void => {
-            this.orchestration.recordError(payload);
+            if (isRecordErrorEnvelope(payload)) {
+                if (!isPlainObject(payload.metadata)) {
+                    throw new Error('IncorrectParametersException');
+                }
+                this.orchestration.recordError(payload.error, payload.metadata);
+            } else {
+                this.orchestration.recordError(payload);
+            }
         },
         registerDomEvents: (payload: any): void => {
             this.orchestration.registerDomEvents(payload);
@@ -48,9 +70,7 @@ export class CommandQueue {
             ) {
                 if (
                     payload.metadata !== undefined &&
-                    (typeof payload.metadata !== 'object' ||
-                        payload.metadata === null ||
-                        Array.isArray(payload.metadata))
+                    !isPlainObject(payload.metadata)
                 ) {
                     throw new Error('IncorrectParametersException');
                 }
diff --git a/packages/slim/src/orchestration/Orchestration.ts b/packages/slim/src/orchestration/Orchestration.ts
index 43df85bb..337f8558 100644
--- a/packages/slim/src/orchestration/Orchestration.ts
+++ b/packages/slim/src/orchestration/Orchestration.ts
@@ -333,8 +333,19 @@ export class Orchestration {
         this.eventCache.recordPageView(payload);
     }
 
-    public recordError(error: any) {
-        this.pluginManager.record('com.amazonaws.rum.js-error', error);
+    /**
+     * Record an error using the JS error plugin.
+     *
+     * @param error An ErrorEvent, Error or primitive.
+     * @param metadata Per-call metadata to attach to the error event. Follows
+     * the same precedence and sanitization rules as recordEvent metadata.
+     */
+    public recordError(error: any, metadata?: EventMetadata) {
+        this.pluginManager.record(
+            'com.amazonaws.rum.js-error',
+            error,
+            metadata
+        );
     }
 
     public registerDomEvents(events: any[]) {
diff --git a/packages/web/src/orchestration/Orchestration.ts b/packages/web/src/orchestration/Orchestration.ts
index bd8b956f..22fee762 100644
--- a/packages/web/src/orchestration/Orchestration.ts
+++ b/packages/web/src/orchestration/Orchestration.ts
@@ -8,7 +8,6 @@ import {
     DOM_EVENT_PLUGIN_ID,
     TargetDomEvent,
     JsErrorPlugin,
-    JS_ERROR_EVENT_PLUGIN_ID,
     NavigationPlugin,
     ResourcePlugin,
     WebVitalsPlugin,
@@ -130,13 +129,6 @@ export class Orchestration extends SlimOrchestration {
         return pluginManager;
     }
 
-    /**
-     * Record an error using the JS error plugin.
-     */
-    public recordError(error: any) {
-        this.pluginManager.record(JS_ERROR_EVENT_PLUGIN_ID, error);
-    }
-
     /**
      * Update DOM plugin to record the (additional) provided DOM events.
      */