{"record":{"id":"1ce56390f2644721","repo":"aeron-io/aeron","slug":"ioexception-message-mappedrawlog","errorCode":null,"errorMessage":"<IOException message>","messagePattern":"<IOException message>","errorType":"exception","errorClass":"UncheckedIOException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/buffer/MappedRawLog.java","lineNumber":130,"sourceCode":"                    mappedBuffers[LOG_META_DATA_SECTION_INDEX] = metaDataMappedBuffer;\n                    logMetaDataBuffer = new UnsafeBuffer(\n                        metaDataMappedBuffer,\n                        metaDataMappingLength - LOG_META_DATA_LENGTH,\n                        LOG_META_DATA_LENGTH);\n                }\n\n                if (!useSparseFiles)\n                {\n                    preTouchPages(termBuffers, termLength, filePageSize);\n                }\n\n                mappedBytesCounter.getAndAddRelease(logLength);\n            }\n        }\n        catch (final IOException ex)\n        {\n            IoUtil.delete(logFile, true);\n            throw new UncheckedIOException(ex);\n        }\n    }\n\n    public int termLength()\n    {\n        return termLength;\n    }\n\n    public boolean free()\n    {\n        final MappedByteBuffer[] mappedBuffers = this.mappedBuffers;\n        if (null != mappedBuffers)\n        {\n            this.mappedBuffers = null;\n            for (int i = 0; i < mappedBuffers.length; i++)\n            {\n                BufferUtil.free(mappedBuffers[i]);\n            }","sourceCodeStart":112,"sourceCodeEnd":148,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/buffer/MappedRawLog.java#L112-L148","documentation":"MappedRawLog's constructor maps the log buffer file and, if mapping fails with an IOException, deletes the partially created log file and rethrows the exception wrapped in UncheckedIOException. This indicates the JVM failed to mmap the term buffer file (most often the file is larger than free addressable space/swap+memory limits, or a filesystem-level error occurred).","triggerScenarios":"Creating a MappedRawLog (via FileStoreLogFactory.newInstance for a new publication or image) where FileChannel.map fails: total log length (3 * termLength, e.g. 3GB+ of mappings) exceeds the JVM's or OS's mapping limits, an I/O error occurs during mapping, or the file was removed/locked concurrently.","commonSituations":"Large term buffers (1GB terms) combined with many streams exhausting address space or vm.max_map_count; low-memory containers where mmap of huge sparse files fails; filesystems that do not support mmap (some network mounts); ulimit restrictions.","solutions":["Reduce term buffer size (aeron.term.buffer.length) or the number of concurrent streams so total mapped bytes fit within limits.","Increase OS limits: vm.max_map_count, ulimit -v, or container memory/mmap limits.","Ensure the data dir is on a filesystem that supports mmap (local ext4/xfs rather than NFS).","Check the cause field of the UncheckedIOException for the concrete IOException (e.g. 'Map failed', ENOMEM).","Free memory or reduce mapped-byte pressure; the failed log file is deleted automatically so no manual cleanup of that file is needed."],"exampleFix":"// before\n-Daeron.term.buffer.length=1073741824  // 1GB terms, mmap fails on constrained host\n// after\n-Daeron.term.buffer.length=16777216    // 16MB terms\n-Daeron.term.buffer.sparse.file=true","handlingStrategy":"validation","validationCode":"void ensureMmapCapacity(long totalLogBytes, int streams) {\n    long est = totalLogBytes * streams;\n    Runtime rt = Runtime.getRuntime();\n    if (est > rt.maxMemory() * 4) {\n        throw new IllegalStateException(\"log allocation \" + est + \" bytes likely exceeds mapping capacity\");\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    publication = aeron.addPublication(channel, streamId);\n} catch (java.io.UncheckedIOException e) {\n    if (e.getCause() instanceof java.io.IOException\n        && String.valueOf(e.getCause()).contains(\"Map failed\")) {\n        // reduce term length / free memory / raise vm.max_map_count, then retry\n    }\n}","preventionTips":["Keep total mapped bytes (streams * 3 * termLength) within OS/JVM mapping limits.","Raise vm.max_map_count and check ulimit -v on hosts with many streams.","Use sparse files for large term buffers.","Ensure the data dir is on an mmap-capable local filesystem, not NFS."],"tags":["java","mmap","memory","unchecked-ioexception"],"backgroundTag":"file-write-failed","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}