Troubleshooting

Unsupported media type

The SDK only accepts .mp4, .mov, and .mkv as input.

base directory is required

Set config.storage.baseDir even for Cloudinary flows. Uploads still depend on a local temporary HLS directory before files are pushed remotely.

Cloudinary cloud name is required or credential errors

Make sure all three credential fields are present:

credentials: {
  cloudName: "...",
  apiKey: "...",
  apiSecret: "...",
}

S3 access key id is required or other S3 credential errors

Make sure all five S3 credential fields are present and non-empty:

credentials: {
  accessKeyId: "...",
  secretAccessKey: "...",
  region: "...",
  bucket: "...",
  folderName: "...",
}

Also make sure storage.type is "s3" before calling processS3().

Request Timeout or HTTP 499

This usually indicates Cloudinary upload pressure or a long-running request. The SDK already uploads in small batches and retries transient timeout failures. If you still see repeated timeouts:

• Reduce the number of generated variants.
• Check your network stability.
• Retry with a smaller source file to isolate whether the issue is payload size or environment-related.

invalid file

This usually points to a malformed or incomplete generated HLS file. Confirm that local HLS generation completed successfully before upload and verify the generated master.m3u8 and segment files exist in the output directory.

S3 playback URL expires too quickly

processS3() returns signed URLs with a short expiration window. Start playback soon after requesting the URL, or call processS3() again to generate a fresh signed URL when needed.

ffmpeg: command not found

Install ffmpeg and make sure it is available on your shell PATH before starting the Node.js process.