{"record":{"id":"9417f27d83221699","repo":"awslabs/llrt","slug":"memory-mapping-failed-unable-to-map-u-bytes-make-sure-you","errorCode":null,"errorMessage":"Memory mapping failed: Unable to map %u bytes. Make sure you have enough memory available","messagePattern":"Memory mapping failed: Unable to map %u bytes\\. Make sure you have enough memory available","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"llrt/src/main.c","lineNumber":211,"sourceCode":"  {\n    logInfo(\"Decompressing using %d threads\\n\", parts);\n  }\n  else\n  {\n    logInfo(\"Decompressing\\n\");\n  }\n\n  readData(data, parts, &inputSizes, &outputSizes, &compressedData, uncompressedSize);\n\n  if (ftruncate(outputFd, *uncompressedSize) == -1)\n  {\n    err(1, \"Failed to set file size\");\n  }\n\n  uncompressed = mmap(NULL, *uncompressedSize, PROT_READ | PROT_WRITE, MAP_SHARED, outputFd, 0);\n  if (uncompressed == MAP_FAILED || !uncompressed)\n  {\n    err(1, \"Memory mapping failed: Unable to map %u bytes. Make sure you have enough memory available\", *uncompressedSize);\n  }\n\n  DecompressThreadArgs args[parts];\n  for (uint32_t i = 0; i < parts; i++)\n  {\n    args[i].inputBuffer = compressedData + inputOffset;\n    args[i].outputBuffer = uncompressed + outputOffset;\n    args[i].srcSize = inputSizes[i];\n    args[i].dstSize = outputSizes[i];\n    args[i].id = i;\n    inputOffset += inputSizes[i];\n    outputOffset += outputSizes[i];\n    if (parts > 1)\n    {\n      pthread_create(&threads[i], NULL, decompressPartial, (void *)&args[i]);\n    }\n    else\n    {","sourceCodeStart":193,"sourceCodeEnd":229,"githubUrl":"https://github.com/awslabs/llrt/blob/742fc00b82cbeaab1c1b76f0d706c302a5cbc306/llrt/src/main.c#L193-L229","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Increase available memory: raise the container/cgroup memory limit or add swap so the full uncompressed size can be mapped.","Check `ulimit -v` (RLIMIT_AS) and remove or raise the address-space limit.","Verify the binary was built correctly — re-download/rebuild; a truncated or corrupted payload yields a bogus uncompressedSize.","Confirm the running kernel supports mmap on memfd (Linux 3.17+ for memfd_create)."],"exampleFix":"// before: docker run --memory=64m llrt-app\n// after: docker run --memory=512m llrt-app","handlingStrategy":"validation","validationCode":"// Verify host memory can back the mapping before launch:\nimport os from 'node:os';\nimport { execFileSync } from 'node:child_process';\nconst sizeBytes = 256 * 1024 * 1024; // expected uncompressed size\nconst freeKb = parseInt(require('fs').readFileSync('/proc/meminfo','utf8').match(/MemAvailable:\\s+(\\d+)/)[1], 10);\nif (freeKb * 1024 < sizeBytes) throw new Error('Not enough memory to extract llrt payload');","typeGuard":null,"tryCatchPattern":"try {\n  child_process.execFileSync('./llrt', ['app.js']);\n} catch (e) {\n  if (e.status === 1 && /Unable to map \\d+ bytes/.test(String(e.stderr))) {\n    // raise container memory limit / add swap, then retry once\n  }\n}","preventionTips":["Size container/cgroup memory limits well above the binary's uncompressed footprint.","Avoid low RLIMIT_AS/RLIMIT_DATA for runtime processes.","Verify binary integrity (checksum) — corruption can produce absurd uncompressedSize values.","Add swap or burst capacity in memory-constrained deployments."],"tags":["mmap","out-of-memory","self-extraction","limits"],"backgroundTag":"mmap-failed","analyzedSha":"742fc00b82cbeaab1c1b76f0d706c302a5cbc306","analyzedAt":"2026-09-12T11:14:07.838Z","contentChangedAt":"2026-09-12T11:14:07.838Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}