Troubleshoot Node.js Media SDK issues

On an Apple Silicon Mac with an arm64 version of Node installed, the npm install of this SDK npm install @twilio/video-node-sdk fails, returning npm error code EBADPLATFORM. To correct this error, switch to an x64 build of Node.js.

The SDK requires an x64 build of Node.js. Rosetta lets an x64 build run on Apple Silicon, but installing Rosetta doesn't change which build of Node.js you have. If your Node.js is an arm64 build, the SDK doesn't install.

To install an x64 build of Node.js on an Apple Silicon (M-series) Mac, follow these steps:

1. In Terminal, install Rosetta:
   Copy code block

   /usr/sbin/softwareupdate --install-rosetta --agree-to-license

2. Install an x64 build of Node.js version 24.0.0 or later. Open a shell that runs under Rosetta, and then install Node.js with nvm:
   Copy code block

   1
   arch -x86_64 zsh
   2
   nvm install 24

3. Confirm that your Node.js install uses the x64 architecture:
   Copy code block

   node -e "console.log(process.arch)"

   A successful install returns x64. If this commands returns arm64, you're running an arm64 build:
   • If you have an arm64 build of Node.js 24, remove it, and then repeat steps 2 and 3:
     Copy code block

     1
     nvm deactivate
     2
     nvm uninstall 24

If npm install fails with npm error code EBADPLATFORM and reports "cpu":"arm64", you're running an arm64 build of Node.js. Follow the preceding steps to switch to an x64 build.

If the SDK throws an UnsupportedPlatformError, there's no prebuilt binary for your platform or architecture. Run the SDK on Linux x86-64, or on macOS x86_64 for local development, with an x64 build of Node.js version 24.0.0 or later. If you use an Apple Silicon Mac, see SDK installation fails on Apple Silicon.

If loading the SDK throws a NativeBindingLoadError that says the prebuilt binary failed to load, check your prerequisites:

1. Confirm that you're running Node.js version 24.0.0 or later:
   Copy code block

   node --version

   On earlier versions, npm installs the SDK with only a warning.
2. On macOS, confirm that you're running macOS 26 or later:
   Copy code block

   sw_vers -productVersion

   The prebuilt binary targets macOS 26. npm can't check the operating system version, so on macOS 25 or earlier the install succeeds and the binary fails to load.
3. On Linux, confirm that the libX11 library is installed:
   Copy code block

   ldconfig -p | grep libX11

   If the command prints nothing, the library is missing. Minimal container images, such as node:24-slim, don't include it. On Debian or Ubuntu, install it:
   Copy code block

   apt-get update && apt-get install -y libx11-6

4. On Linux, confirm that glibc is version 2.34 or later:
   Copy code block

   ldd --version

   The first line of the output shows the glibc version. The SDK doesn't support Alpine or other musl-based distributions.

If the Access Token is malformed, expired, or missing a Video grant, connect() rejects with one of the AccessToken*Error classes, such as AccessTokenInvalidError (20101) or AccessTokenExpiredError (20104). To handle it, wrap await connect() in a try...catch block, then check the following:

1. Set environment variables for TWILIO_ACCOUNT_SID, TWILIO_API_KEY, and TWILIO_API_SECRET.
2. Add a VideoGrant to the token.
3. If the token expired, generate a new one.

If connect() rejects with TypeError: Unknown video codec: <name> or TypeError: Unknown audio codec: <name>, the SDK doesn't support a codec in your connect options. This error can appear when you reuse connect options from the JavaScript SDK, such as preferredVideoCodecs: ['H264'].

The SDK accepts the following values:

• preferredVideoCodecs: 'VP8'
• preferredAudioCodecs: 'opus' and 'PCMU'

Codec names are case-sensitive, so 'vp8' and 'Opus' also fail. In TypeScript, the VideoCodec and AudioCodec types catch unsupported values at compile time. To fix the error, use only the supported values or leave out the option:

1
const room = await connect(token, {
2
  name: 'my-room',
3
  preferredVideoCodecs: ['VP8'],
4
  preferredAudioCodecs: ['opus'],
5
});

To learn more, see Known issues and limitations.

If a remote participant publishes an H.264 video track, the SDK can't subscribe to it. The Room emits trackSubscriptionFailed with a MediaNoSupportedCodecError, which has error code 53404. The SDK supports VP8 video only.

To detect the failure, listen for the event:

1
const { MediaNoSupportedCodecError } = require('@twilio/video-node-sdk');
2

3
room.on('trackSubscriptionFailed', (error, publication, participant) => {
4
  if (error instanceof MediaNoSupportedCodecError) {
5
    console.warn(`Can't subscribe to ${publication.trackName} from ${participant.identity}: unsupported codec`);
6
  }
7
});

To fix the failure, set preferredVideoCodecs: ['VP8'] in the client apps that join the Room. To learn how client SDKs set codec preferences, see Managing codecs.

If your app keeps running after it leaves a Room, the Room still holds its native resources. Call room.dispose() when you finish with a Room. The disconnect() method leaves the Room but doesn't release those resources. The disconnected event is a good place to call dispose():

1
room.on('disconnected', () => {
2
  room.dispose();
3
});

Verify the following in your code:

1. Wait for connect() to resolve, and then push video frames. The SDK drops any video frames that you write before then.
2. Review the parameters you pass to the Room:
   • Pass video frames in the I420 format, which uses the Y'UV color model. Each of y, u, and v is a plane object with its own data, stride, width, and height. Frame width and height must be even.
     • Y: Full-resolution luminance at the full frame width and height
     • U: Blue-difference chrominance (Cb) at half the frame width and height
     • V: Red-difference chrominance (Cr) at half the frame width and height
   • Set Audio frame input to 48 kHz mono S16LE PCM.
     • S: Use Signed positive or negative integer values.
     • 16: Store 16 bits (or two bytes) of data per audio sample.
     • LE: Use the little-endian method to store data placing the least significant byte in the smallest memory address.
     • PCM: Convert data using Pulse-code modulation: the raw, uncompressed audio wave data.
3. Check the return value of write(). It returns false when the SDK drops a frame, and getWriteStats().framesDropped counts the drops.

To inspect a Room's media and connection health beyond your own logs, use Video Insights.

If you can't resolve an issue, contact Twilio Support.