Using FFmpeg max_alloc to Prevent OOM Crashes

Running FFmpeg on low-resource Virtual Private Servers (VPS) frequently leads to unexpected process termination by the Linux Out-Of-Memory (OOM) killer. This guide explains how to use the -max_alloc global option to restrict the maximum size of single memory block allocations. By capping these allocation requests, you can prevent runaway memory spikes from malformed files or unexpectedly large frames and maintain server stability.

What is -max_alloc?

FFmpeg uses an internal memory management wrapper (av_malloc) to allocate memory buffers. By default, FFmpeg allows single memory allocations up to its default limit, which is often around 1GB or higher depending on the platform and version. If a corrupt file or massive uncompressed frame requests a memory chunk that exceeds available system RAM, the operating system forcibly terminates the FFmpeg process to preserve the system.

The -max_alloc option defines the maximum size (in bytes) that FFmpeg can allocate for a single memory block. If a single memory request exceeds this threshold, FFmpeg aborts the operation gracefully with an error code rather than triggering an OS-level OOM crash.

Syntax and Placement

The -max_alloc parameter is a global option and must be placed before the input options (-i) in your command line:

ffmpeg -max_alloc <bytes> -i input.mp4 output.mp4

Because FFmpeg expects the value strictly in bytes, you must calculate the limit based on the target megabytes:

  • 128 MB: 134217728
  • 256 MB: 268435456
  • 512 MB: 536870912
  • 1 GB: 1073741824

Example Implementation

If you are running a server with 1GB of total RAM and want to ensure no single buffer allocation exceeds 256MB, run:

ffmpeg -max_alloc 268435456 -i input.mov -c:v libx264 -crf 23 -c:a aac output.mp4

If an incoming frame or container header requests a buffer larger than 256MB, FFmpeg will halt immediately and log an error similar to:

[fatal] Cannot allocate memory

This prevents your server from freezing or dropping critical services like web servers and databases that share the same memory space.

Important Considerations and Limitations

  1. Single Allocation vs. Total Memory: The -max_alloc option only limits the size of an individual memory allocation block. It does not cap the total cumulative memory used across all running threads and operational buffers. If multiple smaller buffers collectively exceed server RAM, an OOM crash can still occur.
  2. Setting the Value Too Low: Setting this parameter too low will cause legitimate encoding jobs to fail, especially when processing 4K video, complex filtergraphs, or codecs that require large decoding reference frames.
  3. Layering with OS Limits: For full protection on production systems, combine -max_alloc with OS-level restrictions. Use Docker memory flags (--memory=512m), systemd resource controls (MemoryMax=512M), or shell limits (ulimit -v 524288) to constrain total process footprint while using -max_alloc to catch rogue allocation calls inside FFmpeg.