NodeAV

node-av / lib / FFmpegError

Class: FFmpegError ​

Defined in: src/lib/error.ts:141

FFmpeg error handling class.

Provides utilities for handling and converting FFmpeg error codes. FFmpeg uses negative values for errors, with both FFmpeg-specific codes and POSIX error codes converted to negative values. This class provides methods to check, convert, and throw errors based on FFmpeg return codes.

Example ​

typescript
import { FFmpegError } from 'node-av';
import { AVERROR_EAGAIN, AVERROR_EOF } from 'node-av/constants';

// Check and throw errors
const ret = await codecContext.sendPacket(packet);
FFmpegError.throwIfError(ret, 'sendPacket');

// Handle specific errors
if (ret === AVERROR_EAGAIN) {
  // Need to receive frames first
} else if (ret === AVERROR_EOF) {
  // End of stream
}

// Get error description
const errorMsg = FFmpegError.strerror(ret);
console.error(`Error: ${errorMsg}`);

See ​

av_strerror - FFmpeg Doxygen

Extends ​

  • Error

Implements ​

Constructors ​

Constructor ​

new FFmpegError(code?): FFmpegError

Defined in: src/lib/error.ts:144

Parameters ​

code? ​

number

Returns ​

FFmpegError

Overrides ​

Error.constructor

Properties ​

cause? ​

optional cause?: unknown

Defined in: node_modules/typescript/lib/lib.es2022.error.d.ts:26

Inherited from ​

Error.cause

name ​

name: string

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from ​

Error.name

stack? ​

optional stack?: string

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1078

Inherited from ​

Error.stack

stackTraceLimit ​

static stackTraceLimit: number

Defined in: node_modules/@types/node/globals.d.ts:67

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Inherited from ​

Error.stackTraceLimit

Accessors ​

code ​

Get Signature ​

get code(): number

Defined in: src/lib/error.ts:315

Error code.

The FFmpeg error code (negative value).

Returns ​

number

isEACCES ​

Get Signature ​

get isEACCES(): boolean

Defined in: src/lib/error.ts:384

Whether this is EACCES (permission denied).

Returns ​

boolean

isEAGAIN ​

Get Signature ​

get isEAGAIN(): boolean

Defined in: src/lib/error.ts:342

Whether this is EAGAIN (resource temporarily unavailable).

In codec/filter contexts this means "output not available yet, feed more input" rather than a hard failure.

Example ​
typescript
const error = FFmpegError.fromCode(ret);
if (error?.isEAGAIN) {
  // send more input, then retry
}
Returns ​

boolean

isEINVAL ​

Get Signature ​

get isEINVAL(): boolean

Defined in: src/lib/error.ts:363

Whether this is EINVAL (invalid argument).

Returns ​

boolean

isEIO ​

Get Signature ​

get isEIO(): boolean

Defined in: src/lib/error.ts:391

Whether this is EIO (I/O error).

Returns ​

boolean

isENOENT ​

Get Signature ​

get isENOENT(): boolean

Defined in: src/lib/error.ts:377

Whether this is ENOENT (no such file or directory).

Returns ​

boolean

isENOMEM ​

Get Signature ​

get isENOMEM(): boolean

Defined in: src/lib/error.ts:370

Whether this is ENOMEM (out of memory).

Returns ​

boolean

isEOF ​

Get Signature ​

get isEOF(): boolean

Defined in: src/lib/error.ts:349

Whether this is the end of stream (AVERROR_EOF).

Returns ​

boolean

isEPIPE ​

Get Signature ​

get isEPIPE(): boolean

Defined in: src/lib/error.ts:398

Whether this is EPIPE (broken pipe).

Returns ​

boolean

isExit ​

Get Signature ​

get isExit(): boolean

Defined in: src/lib/error.ts:405

Whether this is the immediate-exit request (AVERROR_EXIT).

Returns ​

boolean

isInvalidData ​

Get Signature ​

get isInvalidData(): boolean

Defined in: src/lib/error.ts:356

Whether this is invalid data found while processing input (AVERROR_INVALIDDATA).

Returns ​

boolean

message ​

Get Signature ​

get message(): string

Defined in: src/lib/error.ts:324

Error message.

Human-readable description of the error.

Returns ​

string

Overrides ​

Error.message

Methods ​

getNative() ​

getNative(): NativeFFmpegError

Defined in: src/lib/error.ts:437

Internal

Get the underlying native FFmpegError object.

Returns ​

NativeFFmpegError

The native FFmpegError binding object

Implementation of ​

NativeWrapper.getNative

is() ​

is(errorCode): boolean

Defined in: src/lib/error.ts:426

Check if this error matches a specific code.

Parameters ​

errorCode ​

number

FFmpeg error code to compare against

Returns ​

boolean

True if this error's code matches

Example ​

typescript
import { AVERROR_DECODER_NOT_FOUND } from 'node-av/constants';

const error = FFmpegError.fromCode(ret);
if (error?.is(AVERROR_DECODER_NOT_FOUND)) {
  // handle missing decoder
}

AVERROR() ​

static AVERROR(errorName): AVError

Defined in: src/lib/error.ts:200

Convert POSIX error name to FFmpeg error code.

Converts platform-specific POSIX error to FFmpeg's negative error code.

Direct mapping to AVERROR() macro.

Parameters ​

errorName ​

PosixError

POSIX error name

Returns ​

AVError

FFmpeg error code

Example ​

typescript
import { PosixError } from 'node-av';

const code = FFmpegError.AVERROR(PosixError.ENOMEM);
// Returns platform-specific negative error code

See ​

PosixError For available error names

captureStackTrace() ​

static captureStackTrace(targetObject, constructorOpt?): void

Defined in: node_modules/@types/node/globals.d.ts:51

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

js
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters ​

targetObject ​

object

constructorOpt? ​

Function

Returns ​

void

Inherited from ​

Error.captureStackTrace

fromCode() ​

static fromCode(code): FFmpegError | null

Defined in: src/lib/error.ts:245

Create error from code.

Creates an FFmpegError instance if the code is an error.

Parameters ​

code ​

number

FFmpeg return code

Returns ​

FFmpegError | null

Error instance or null if not an error

Example ​

typescript
const error = FFmpegError.fromCode(ret);
if (error) {
  console.error(`Error: ${error.message}`);
}

is() ​

static is(code, errorCode): boolean

Defined in: src/lib/error.ts:306

Check if code matches specific error.

Convenience method to check for specific error codes.

Parameters ​

code ​

number

Return code to check

errorCode ​

number

Error code to compare against

Returns ​

boolean

True if codes match

Example ​

typescript
import { AVERROR_EOF } from 'node-av/constants';

if (FFmpegError.is(ret, AVERROR_EOF)) {
  console.log('End of file reached');
}

isError() ​

static isError(error): error is Error

Defined in: node_modules/typescript/lib/lib.esnext.error.d.ts:23

Indicates whether the argument provided is a built-in Error instance or not.

Parameters ​

error ​

unknown

Returns ​

error is Error

Inherited from ​

Error.isError

isFFmpegError() ​

static isFFmpegError(code): boolean

Defined in: src/lib/error.ts:221

Check if a code is an FFmpeg error.

FFmpeg errors are negative values.

Parameters ​

code ​

number

Return code to check

Returns ​

boolean

True if code is an error

Example ​

typescript
const ret = await formatContext.readFrame(packet);
if (FFmpegError.isFFmpegError(ret)) {
  console.error('Read failed');
}

prepareStackTrace() ​

static prepareStackTrace(err, stackTraces): any

Defined in: node_modules/@types/node/globals.d.ts:55

Parameters ​

err ​

Error

stackTraces ​

CallSite[]

Returns ​

any

See ​

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from ​

Error.prepareStackTrace

strerror() ​

static strerror(errnum): string

Defined in: src/lib/error.ts:175

Get human-readable error message for code.

Converts an FFmpeg error code to a descriptive string.

Direct mapping to av_strerror().

Parameters ​

errnum ​

number

FFmpeg error code

Returns ​

string

Error description string

Example ​

typescript
const message = FFmpegError.strerror(-22);
console.log(message); // "Invalid argument"

throwIfError() ​

static throwIfError(code, operation?): void

Defined in: src/lib/error.ts:276

Throw if code indicates an error.

Checks if the code is an error and throws an FFmpegError if so. Commonly used pattern for FFmpeg API calls.

Parameters ​

code ​

number

FFmpeg return code

operation? ​

string

Optional operation name for context

Returns ​

void

Throws ​

If code is negative

Example ​

typescript
// Simple error check
const ret = codecContext.open(codec);
FFmpegError.throwIfError(ret);

// With operation context
const ret2 = await formatContext.writeHeader();
FFmpegError.throwIfError(ret2, 'writeHeader');
// Throws: "writeHeader failed: [error message]"