Troubleshooting - node-webcodecs

Common Issues

This guide covers the most frequently encountered issues when using node-webcodecs.

Memory Leaks

Symptom

Application memory usage continuously increases, eventually crashing with:

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

Cause

VideoFrame objects not being closed after use.

Solution

Always call .close() on frames immediately after encoding/decoding:

const frame = new VideoFrame(data, options);
encoder.encode(frame);
// frame never closed - MEMORY LEAK!

Why this happens:

VideoFrame wraps native C++ memory
JavaScript garbage collector doesn’t see this memory
Must be manually freed with .close()

Memory Leak DetectionMonitor memory usage during development:

node --expose-gc --trace_gc your-script.js

Or use:

setInterval(() => {
  const used = process.memoryUsage().heapUsed / 1024 / 1024;
  console.log(`Memory: ${Math.round(used)} MB`);
}, 1000);

Encoder/Decoder Errors

”Encoder is not configured”

Error: Cannot encode frame: encoder is not configured

Cause: Encoding before calling configure() Solution:

const encoder = new VideoEncoder({ ... });
encoder.configure({ codec: 'avc1.42E01E', width: 1920, height: 1080 });  // ← Must configure first
encoder.encode(frame);

“Invalid codec string”

Error: Unknown codec: 'h265'

Cause: Incorrect codec identifier Solution: Use proper codec strings:

// ❌ Wrong
codec: 'h265'
codec: 'h264'

// ✅ Correct
codec: 'avc1.42E01E'   // H.264
codec: 'hev1.1.6.L93.B0'  // HEVC
codec: 'vp09.00.10.08'    // VP9

See Codec Reference for full list.

”Encoder closed”

Error: Cannot encode frame: encoder is closed

Cause: Encoding after calling encoder.close() Solution:

// Don't call encoder.close() until done encoding
await encoder.flush();  // Wait for all frames
encoder.close();        // Then close

Frame Format Issues

”Unsupported format”

Error: Unsupported pixel format: RGB

Cause: Using unsupported pixel format Solution: Use supported formats:

// Supported formats
format: 'RGBA'    // ✓ Most common
format: 'I420'    // ✓ YUV 4:2:0
format: 'NV12'    // ✓ YUV 4:2:0 (hardware)
format: 'I010'    // ✓ 10-bit YUV

// Not supported
format: 'RGB'     // ✗
format: 'BGR'     // ✗

Wrong Buffer Size

Error: Buffer size mismatch

Cause: Buffer doesn’t match frame dimensions Solution:

const width = 1920;
const height = 1080;

// RGBA: width × height × 4 bytes
const rgbaSize = width * height * 4;
const rgbaBuffer = new Uint8Array(rgbaSize);

// I420: width × height × 1.5 bytes
const i420Size = Math.floor(width * height * 1.5);
const i420Buffer = new Uint8Array(i420Size);

Timestamp Issues

Video Plays Too Fast/Slow

Cause: Wrong timestamp units Solution: Use microseconds, not milliseconds:

// ❌ Wrong (milliseconds)
timestamp: i * 33  // Will play 1000x too fast!

// ✅ Correct (microseconds)
timestamp: i * 33333  // 30 fps
timestamp: i * 16667  // 60 fps
timestamp: i * 1_000_000 / fps  // General formula

Frames Out of Order

Cause: Incorrect timestamp ordering Solution: Ensure monotonically increasing timestamps:

for (let i = 0; i < frames.length; i++) {
  const timestamp = i * frameDuration;  // ✓ Always increasing
  frame.timestamp = timestamp;
}

Hardware Acceleration Issues

”Hardware encoder not found”

Error: Unknown encoder 'h264_videotoolbox'

Cause: FFmpeg not compiled with hardware support Solution: Check available encoders:

ffmpeg -encoders | grep videotoolbox  # macOS
ffmpeg -encoders | grep nvenc          # NVIDIA
ffmpeg -encoders | grep qsv            # Intel

If missing, reinstall FFmpeg with hardware support:

# macOS
brew reinstall ffmpeg

# Linux (compile from source)
./configure --enable-nvenc --enable-videotoolbox

Hardware Encoder Fails

Solution: Fallback to software encoder:

let codec = 'h264_videotoolbox';

const support = await VideoEncoder.isConfigSupported({
  codec,
  width: 1920,
  height: 1080
});

if (!support.supported) {
  console.warn('Hardware encoder unavailable, using software');
  codec = 'avc1.42E01E';  // Software fallback
}

encoder.configure({ codec, width: 1920, height: 1080 });

Performance Issues

Slow Encoding

Symptoms:

Encoding takes too long
High CPU usage
Dropped frames

Solutions:

Use hardware acceleration

encoder.configure({
  codec: 'h264_videotoolbox',  // 8-15x faster
  hardwareAcceleration: 'prefer-hardware'
});

Reduce resolution

// Instead of 4K:
width: 3840, height: 2160

// Try 1080p:
width: 1920, height: 1080  // 4x faster

Lower framerate

framerate: 30  // Instead of 60

Use worker threads

See Worker Threads Guide for parallel encoding.

High Memory Usage

Solutions:

Close frames immediately

encoder.encode(frame);
frame.close();  // Don't wait

Limit queue size

if (encoder.encodeQueueSize > 10) {
  await encoder.flush();  // Wait before adding more
}

Process in batches

// Instead of loading all frames:
for (const frame of allFrames) { ... }

// Process in chunks:
for (let i = 0; i < total; i += 100) {
  const batch = frames.slice(i, i + 100);
  await processBatch(batch);
}

Platform-Specific Issues

macOS

Issue: “Operation not permitted” errors Solution: Grant permissions for video acceleration:

# Reset permissions
tccutil reset All

# Or grant manually:
# System Preferences > Security & Privacy > Camera/Screen Recording

Linux

Issue: NVIDIA encoder not working Solution:

Install NVIDIA drivers

Compile FFmpeg with NVENC support:

sudo apt install nvidia-cuda-toolkit
./configure --enable-nvenc --enable-cuda-nvcc

Windows

Issue: DirectX errors Solution: Update graphics drivers:

NVIDIA: GeForce Experience
AMD: AMD Software
Intel: Intel Driver & Support Assistant

Debugging Tips

Enable Detailed Logging

// Add error handlers
const encoder = new VideoEncoder({
  output: (chunk, metadata) => {
    console.log(`Encoded: ${chunk.byteLength} bytes, type: ${chunk.type}`);
  },
  error: (err) => {
    console.error('Encoder error:', err.message);
    console.error('Stack:', err.stack);
  }
});

// Log state changes
console.log('Encoder state:', encoder.state);
console.log('Queue size:', encoder.encodeQueueSize);

Test With Simple Example

If having issues, test with the most basic example:

const { VideoEncoder, VideoFrame } = require('node-webcodecs');

const encoder = new VideoEncoder({
  output: (chunk) => console.log(`Chunk: ${chunk.byteLength} bytes`),
  error: (err) => console.error('Error:', err)
});

encoder.configure({
  codec: 'avc1.42E01E',
  width: 640,
  height: 480,
  bitrate: 1_000_000
});

const data = new Uint8Array(640 * 480 * 4).fill(255);
const frame = new VideoFrame(data, {
  format: 'RGBA',
  codedWidth: 640,
  codedHeight: 480,
  timestamp: 0
});

encoder.encode(frame);
frame.close();

await encoder.flush();
encoder.close();

console.log('✓ Basic test passed');

Check FFmpeg Installation

# Verify FFmpeg is installed
ffmpeg -version

# Check available codecs
ffmpeg -codecs | grep h264
ffmpeg -codecs | grep hevc
ffmpeg -codecs | grep vp9

# Check hardware encoders
ffmpeg -encoders | grep videotoolbox
ffmpeg -encoders | grep nvenc
ffmpeg -encoders | grep qsv

Getting Help

If you’re still stuck:

Check GitHub Issues: https://github.com/caseymanos/node-webcodecs/issues
Create a minimal reproduction
Include:
- node-webcodecs version (npm list node-webcodecs)
- Node.js version (node --version)
- Operating system
- Error message and stack trace
- Minimal code to reproduce

Next Steps

API Reference

Complete API documentation

Examples

Working code examples

GitHub Issues

Report bugs and get help

Quick Start

Back to basics

Getting Started

Migration Guides

API Reference

Guides

Cookbook

Examples

Help

​Common Issues

​Memory Leaks

​Symptom

​Cause

​Solution

​Encoder/Decoder Errors

​”Encoder is not configured”

​“Invalid codec string”

​”Encoder closed”

​Frame Format Issues

​”Unsupported format”

​Wrong Buffer Size

​Timestamp Issues

​Video Plays Too Fast/Slow

​Frames Out of Order

​Hardware Acceleration Issues

​”Hardware encoder not found”

​Hardware Encoder Fails

​Performance Issues

​Slow Encoding

​High Memory Usage

​Platform-Specific Issues

​macOS

​Linux

​Windows

​Debugging Tips

​Enable Detailed Logging

​Test With Simple Example

​Check FFmpeg Installation

​Getting Help

​Next Steps

API Reference

Examples

GitHub Issues

Quick Start

Common Issues

Memory Leaks

Symptom

Cause

Solution

Encoder/Decoder Errors

”Encoder is not configured”

“Invalid codec string”

”Encoder closed”

Frame Format Issues

”Unsupported format”

Wrong Buffer Size

Timestamp Issues

Video Plays Too Fast/Slow

Frames Out of Order

Hardware Acceleration Issues

”Hardware encoder not found”

Hardware Encoder Fails

Performance Issues

Slow Encoding

High Memory Usage

Platform-Specific Issues

macOS

Linux

Windows

Debugging Tips

Enable Detailed Logging

Test With Simple Example

Check FFmpeg Installation

Getting Help

Next Steps