tursodatabase/turso · critical

mmap failed: {}

Error message

mmap failed: {}

What it means

The Unix buffer-pool arena backs its allocation with one anonymous mmap (PROT_READ|PROT_WRITE, plus MADV_HUGEPAGE on Linux). If mmap returns MAP_FAILED, alloc panics with the OS error - typically ENOMEM from exhausted address space, strict overcommit accounting, or container memory caps.

Source

Thrown at core/storage/buffer_pool.rs:458

}

#[cfg(all(unix, not(miri)))]
mod arena {
    use libc::MAP_ANONYMOUS;
    use libc::{mmap, munmap, MAP_PRIVATE, PROT_READ, PROT_WRITE};
    use std::ffi::c_void;

    pub unsafe fn alloc(len: usize) -> *mut u8 {
        let ptr = mmap(
            std::ptr::null_mut(),
            len,
            PROT_READ | PROT_WRITE,
            MAP_PRIVATE | MAP_ANONYMOUS,
            -1,
            0,
        );
        if ptr == libc::MAP_FAILED {
            panic!("mmap failed: {}", std::io::Error::last_os_error());
        }
        #[cfg(target_os = "linux")]
        {
            libc::madvise(ptr, len, libc::MADV_HUGEPAGE);
        }
        ptr as *mut u8
    }

    pub unsafe fn dealloc(ptr: *mut u8, len: usize) {
        let result = munmap(ptr as *mut c_void, len);
        if result != 0 {
            panic!("munmap failed: {}", std::io::Error::last_os_error());
        }
    }
}

#[cfg(any(not(unix), miri))]
mod arena {

View on GitHub (pinned to 244cde92a7)

Solutions

1. Size the buffer pool to fit the container/VM memory budget
2. Raise the limit: increase the cgroup memory limit or RLIMIT_AS (ulimit -v), or relax overcommit (vm.overcommit_memory=1)
3. Check dmesg for OOM/commit-accounting messages to confirm the ENOMEM source
4. Note the non-Unix/miri build falls back to the std allocator when mmap is unavailable

Example fix

# before
# container capped at 2G; pool asks for far more -> panic: mmap failed: Cannot allocate memory

# after
docker run -m 8g ...              # raise the memory limit
# or: sysctl vm.overcommit_memory=1  # allow the reservation
# or configure a smaller buffer pool

// check headroom before creating the pool
let avail = available_virtual_memory()?; // read /proc/meminfo CommitLimit or sysinfo crate
assert!(pool_bytes + reserved <= avail, "buffer pool exceeds address space");

When it happens

Trigger: Creating or growing the buffer pool beyond available virtual memory: vm.overcommit_memory=2 with a small CommitLimit, cgroup or RLIMIT_AS container limits, 32-bit targets, or pathologically huge pool sizes.

Common situations: Containers with strict memory limits; CI runners; strict overcommit configuration; disabled swap with commit accounting.

Related errors

• munmap failed: {}
• Pool not initialized
• buffer not loaded
• OpenRead on pseudo cursor
• Rewind on non-btree/materialized-view cursor

AI-assisted analysis of tursodatabase/turso@244cde92a7 (2026-08-20). Data as JSON: /api/errors/2f4740e09437210f. Report an issue: GitHub.