EC
ERR_MISSING_MESSAGE_PORT_IN_TRANSFER_LIST
Node.jsERRORNotableWorkerHIGH confidence

MessagePort in message data must also be in transfer list

Production Risk

Low — caught immediately; always pair MessagePort usage with the transfer list.

What this means

Thrown when a MessagePort object is included in the message data of postMessage() but is not also listed in the transfer list. MessagePort objects must be transferred (not cloned) and must appear in the transferList array to be moved to the receiving context.

Why it happens
  1. 1Passing a MessagePort in the message without including it in the transferList
  2. 2Forgetting to add the port to the second argument of postMessage()
How to reproduce

Triggered when postMessage() serialises the message and finds a MessagePort not in the transfer list.

trigger — this will error
trigger — this will error
const { Worker, MessageChannel } = require('worker_threads');
const { port1, port2 } = new MessageChannel();
const worker = new Worker('./w.js');
// port2 in message but not in transfer list — throws
worker.postMessage({ port: port2 }, []);

expected output

Error [ERR_MISSING_MESSAGE_PORT_IN_TRANSFER_LIST]: MessagePort was found in message but not listed in transferList

Fix

Include the MessagePort in the transferList

WHEN When passing MessagePorts via postMessage()

Include the MessagePort in the transferList
const { Worker, MessageChannel } = require('worker_threads');
const { port1, port2 } = new MessageChannel();
const worker = new Worker('./w.js');
worker.postMessage({ port: port2 }, [port2]); // port2 in both message and transferList

Why this works

Listing the port in the transferList transfers ownership to the worker, satisfying the serialisation requirement.

Code examples
Triggerjs
const { Worker, MessageChannel } = require('worker_threads');
const { port1, port2 } = new MessageChannel();
const worker = new Worker('./w.js');
// port2 in message but not in transfer list — throws
worker.postMessage({ port: port2 }, []);  // this triggers ERR_MISSING_MESSAGE_PORT_IN_TRANSFER_LIST
Handle in try/catchjs
try {
  // operation that may throw ERR_MISSING_MESSAGE_PORT_IN_TRANSFER_LIST
  riskyOperation()
} catch (err) {
  if (err.code === 'ERR_MISSING_MESSAGE_PORT_IN_TRANSFER_LIST') {
    console.error('ERR_MISSING_MESSAGE_PORT_IN_TRANSFER_LIST:', err.message)
  } else {
    throw err
  }
}
Defensive pattern to avoid itjs
// Validate inputs before calling the operation
function safe_err_missing_message_port_in_transfer_list(...args) {
  // validate args here
  return performOperation(...args)
}
What not to do

✕ Include MessagePort in message data without adding it to transferList

MessagePorts cannot be cloned; they must be explicitly transferred.

Sources
Official documentation ↗

Node.js Error Codes Documentation

Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev

← All Node.js errors