awslabs/llrt · critical

Memory mapping failed: Unable to map %u bytes. Make sure…

Error message

Memory mapping failed: Unable to map %u bytes. Make sure you have enough memory available

What it means

After sizing the output memfd, decompress() mmaps *uncompressedSize bytes of it PROT_READ|PROT_WRITE MAP_SHARED to decompress in place. This error means mmap returned MAP_FAILED (or NULL), so the runtime could not map the output region into the address space. It is a hard abort — the payload cannot be extracted without this mapping.

Solutions

1. Increase available memory: raise the container/cgroup memory limit or add swap so the full uncompressed size can be mapped.
2. Check `ulimit -v` (RLIMIT_AS) and remove or raise the address-space limit.
3. Verify the binary was built correctly — re-download/rebuild; a truncated or corrupted payload yields a bogus uncompressedSize.
4. Confirm the running kernel supports mmap on memfd (Linux 3.17+ for memfd_create).

Example fix

// before: docker run --memory=64m llrt-app
// after: docker run --memory=512m llrt-app

// Verify host memory can back the mapping before launch:
import os from 'node:os';
import { execFileSync } from 'node:child_process';
const sizeBytes = 256 * 1024 * 1024; // expected uncompressed size
const freeKb = parseInt(require('fs').readFileSync('/proc/meminfo','utf8').match(/MemAvailable:\s+(\d+)/)[1], 10);
if (freeKb * 1024 < sizeBytes) throw new Error('Not enough memory to extract llrt payload');

try {
  child_process.execFileSync('./llrt', ['app.js']);
} catch (e) {
  if (e.status === 1 && /Unable to map \d+ bytes/.test(String(e.stderr))) {
    // raise container memory limit / add swap, then retry once
  }
}

When it happens

Trigger: mmap fails because the system is out of memory or address space (ENOMEM), *uncompressedSize is 0 or absurdly large (corrupt/truncated embedded payload making readData compute a bogus uncompressedSize), or RLIMIT_AS/RLIMIT_DATA blocks the mapping.

Common situations: Running llrt in a memory-constrained container or VPS where uncompressed size exceeds available RAM+swap; a corrupted or wrongly-built binary whose embedded payload header reports a huge uncompressedSize; cgroup memory limits (docker --memory) too low.

Related errors

• Failed to set file size
• failed to decompress
• Failed to unmap memory

AI-assisted analysis of awslabs/llrt@742fc00b82 (2026-09-12). Data as JSON: /api/errors/9417f27d83221699. Report an issue: GitHub.

Appendix: source

Thrown at llrt/src/main.c:211

  {
    logInfo("Decompressing using %d threads\n", parts);
  }
  else
  {
    logInfo("Decompressing\n");
  }

  readData(data, parts, &inputSizes, &outputSizes, &compressedData, uncompressedSize);

  if (ftruncate(outputFd, *uncompressedSize) == -1)
  {
    err(1, "Failed to set file size");
  }

  uncompressed = mmap(NULL, *uncompressedSize, PROT_READ | PROT_WRITE, MAP_SHARED, outputFd, 0);
  if (uncompressed == MAP_FAILED || !uncompressed)
  {
    err(1, "Memory mapping failed: Unable to map %u bytes. Make sure you have enough memory available", *uncompressedSize);
  }

  DecompressThreadArgs args[parts];
  for (uint32_t i = 0; i < parts; i++)
  {
    args[i].inputBuffer = compressedData + inputOffset;
    args[i].outputBuffer = uncompressed + outputOffset;
    args[i].srcSize = inputSizes[i];
    args[i].dstSize = outputSizes[i];
    args[i].id = i;
    inputOffset += inputSizes[i];
    outputOffset += outputSizes[i];
    if (parts > 1)
    {
      pthread_create(&threads[i], NULL, decompressPartial, (void *)&args[i]);
    }
    else
    {

View on GitHub (pinned to 742fc00b82)