← Home
Core Concepts

Error Handling

MediaX implements a comprehensive, typed, and event-driven error handling system with standardized validation errors, pipeline errors, and FFmpeg execution errors.

Error Classes

MediaXError

Base error class with standardized error codes

Properties:

code: string
jobType?: JobType

MediaXValidationError

Parameter/input validation failures before job runs

Properties:

Extends MediaXError
Thrown synchronously

MediaXFFmpegError

FFmpeg execution failures with process details

Properties:

exitCode?: number
stderr?: string
error-classes.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
typescript

Error Codes

Defined in ERROR_CODES for strict type-safety:

Validation

VALIDATION_ERRORFILE_NOT_FOUNDPERMISSION_DENIEDINVALID_PARAMS

Pipeline

PIPELINE_RUNNINGPIPELINE_ABORTEDPIPELINE_ERROR

Jobs

JOB_TIMEOUTJOB_FAILED

FFmpeg

FFMPEG_ERRORFFMPEG_MISSINGNO_STREAMSINVALID_MEDIACONVERSION_FAILEDCODEC_NOT_SUPPORTED

Generic

MEDIAX_ERRORUNKNOWN
[4]

Job-Level Error Handling

Each job emits errors via the event system:

job-error-handling.ts
1
2
3
4
5
6
7
8
typescript

Error Timing:

  • Validation errors (MediaXValidationError) are thrown synchronously on creation
  • Runtime errors (MediaXFFmpegError / MediaXError) are emitted asynchronously

Pipeline Error Handling

Pipelines centralize and normalize errors across multiple steps:

pipeline-error-handling.ts
1
2
3
4
5
6
7
8
9
10
11
12
typescript

Pipeline Features:

Preflight validation prevents execution if configs are invalid
Abortable with cleanup and proper error emission
Timeouts per job type (e.g., compress: 20min, thumbnail: 2min)
Smart enhancement maps raw FFmpeg errors to ERROR_CODES

Queue Error Handling

queue-error-handling.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
typescript

Error Recovery Strategies

Retry on Failure

Automatically retry failed jobs with exponential backoff

job.on("error", () => queue.add(job));

Continue on Error

Skip failed jobs and continue pipeline execution

pipeline.on("error", () => pipeline.run());

Warning Handling

Handle non-critical validation warnings gracefully

pipeline.on("warning", (warn) => log(warn));

Abort & Cleanup

Gracefully abort pipelines and clean up resources

pipeline.abort();
advanced-recovery.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
typescript

Best Practices

Always Attach Error Listeners

Critical

Prevent uncaught exceptions by handling all error events

Use Error Codes for Logic

Important

Use err.code for programmatic handling (e.g., retry only on JOB_TIMEOUT)

Log FFmpeg stderr

Important

Log stderr when catching MediaXFFmpegError for debugging

Validate Before Processing

Recommended

Check file existence and permissions before heavy operations

Key Guidelines:

  • • Always attach error listeners on both jobs and pipelines
  • • Use err.code for programmatic handling
  • • Log stderr when catching MediaXFFmpegError
  • • Combine with warning events for soft failures in batch processing
  • • Validate file existence and permissions before heavy operations

Common Error Scenarios

error-scenarios.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
typescript

Build Robust Applications

With comprehensive error handling knowledge, you're ready to build production-ready applications. Explore the API reference or see practical examples.

Explore API ReferenceView Error Examples