java.lang.OutOfMemoryError: Map failed

I recently encountered this exception and found that many open-source frameworks use FileChannel’s map method for fast file reads and writes, as in the following example:

1
at sun.nio.ch.FileChannelImpl.map0(Native Method) ~[?:1.8.0_40]
2
at sun.nio.ch.FileChannelImpl.map(FileChannelImpl.java:904) ~[?:1.8.0_40]

This method maps a file into off-heap memory, allowing fast file access through memory reads and writes. Here is a diagram taken from Zhihu.

Problems and Solutions

So far, I have encountered this exception in both MapDB and Phoenix. MapDB maps database files directly into off-heap memory for efficient reads and writes. When a Phoenix result set is too large, it must be spilled to a temporary file, which is accessed using mmap.

There are many causes of Map Failed:

1. A 32-bit JVM has a 32-bit address space: 2^32 = 4 GB, so the maximum file size we can map is 4 GB. In practice, other objects also occupy address space, so normally only about 1 GB can be mapped.
2. Java programs have a default maxDirectMemory, the maximum off-heap memory available to the JVM. It is easy to exceed it and trigger an exception, for example when a Phoenix query returns an excessively large result set.
3. The number of mmap handles exceeds the system’s default maximum. Check the system limit with cat /proc/sys/vm/max_map_count and a process’s handle count with cat /proc/$PID/maps | wc -l. Every allocated ByteBuffer corresponds to an mmap handle, so creating many small ByteBuffers makes the handle count rise rapidly. These handles are reclaimed when their ByteBuffers are reclaimed; garbage collection of off-heap memory requires an explicit call to System.gc.

Solutions:

1. Upgrade a 32-bit JVM to 64-bit to obtain a larger address space.
2. On a 64-bit JVM, if the off-heap limit is exceeded only slightly and total memory usage is below 32 GB, use -XX to reduce object size.
3. Adjust -XX to allow more off-heap memory.
4. Adjust /proc/sys/vm/max_map_count.