Troubleshoot Node.js Media SDK issues

The native binary only works on 64-bit systems.

1. On an Apple Silicon (M-series) Mac, install Rosetta.
   Copy code block

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

2. Install Node.js.
   If the installation fails, the command returns npm error code EBADPLATFORM.
3. Verify that the Node installed a 64-bit version.
   Copy code block

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

   macOS running Apple Silicon returns arm64.

This error means the native addon isn't present for your platform and architecture. Confirm you're on a supported platform (Linux x64 or macOS x64) and running an x64 build of Node.js version 24 or later, then reinstall the SDK package.

If the token expired or the token was malformed, it returns a disconnected or connectFailure event with an AccessTokenInvalidError.

1. Set environment variables for TWILIO_ACCOUNT_SID, TWILIO_API_KEY, and TWILIO_API_SECRET.
2. The token carries a VideoGrant.

Verify two actions in your code:

1. Resolve connect(), then push frames. Any frames before that resolution get dropped.
2. Review the parameters you pass to the Room:
   • Set Video using the Y'UV color model. Set the Y, U, and V strides to the plane widths and the frame dimensions.
     • Y: Full-resolution luminance at the full frame height
     • U: Blue-difference chrominance (Cb) at half the frame height
     • V: Red-difference chrominance (Cr) at half the frame 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.

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.