What causes " " in aeron-io/aeron?

Reduce term buffer size (aeron.term.buffer.length) or the number of concurrent streams so total mapped bytes fit within limits.

aeron-io/aeron · error · UncheckedIOException

<IOException message>

Error message

<IOException message>

What it means

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).

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.

Example fix

// before
-Daeron.term.buffer.length=1073741824  // 1GB terms, mmap fails on constrained host
// after
-Daeron.term.buffer.length=16777216    // 16MB terms
-Daeron.term.buffer.sparse.file=true

Defensive patterns

Strategy: validation

Validate before calling

void ensureMmapCapacity(long totalLogBytes, int streams) {
    long est = totalLogBytes * streams;
    Runtime rt = Runtime.getRuntime();
    if (est > rt.maxMemory() * 4) {
        throw new IllegalStateException("log allocation " + est + " bytes likely exceeds mapping capacity");
    }
}

Try / catch

try {
    publication = aeron.addPublication(channel, streamId);
} catch (java.io.UncheckedIOException e) {
    if (e.getCause() instanceof java.io.IOException
        && String.valueOf(e.getCause()).contains("Map failed")) {
        // reduce term length / free memory / raise vm.max_map_count, then retry
    }
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/1ce56390f2644721. Report an issue: GitHub.

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/buffer/MappedRawLog.java:130

                    mappedBuffers[LOG_META_DATA_SECTION_INDEX] = metaDataMappedBuffer;
                    logMetaDataBuffer = new UnsafeBuffer(
                        metaDataMappedBuffer,
                        metaDataMappingLength - LOG_META_DATA_LENGTH,
                        LOG_META_DATA_LENGTH);
                }

                if (!useSparseFiles)
                {
                    preTouchPages(termBuffers, termLength, filePageSize);
                }

                mappedBytesCounter.getAndAddRelease(logLength);
            }
        }
        catch (final IOException ex)
        {
            IoUtil.delete(logFile, true);
            throw new UncheckedIOException(ex);
        }
    }

    public int termLength()
    {
        return termLength;
    }

    public boolean free()
    {
        final MappedByteBuffer[] mappedBuffers = this.mappedBuffers;
        if (null != mappedBuffers)
        {
            this.mappedBuffers = null;
            for (int i = 0; i < mappedBuffers.length; i++)
            {
                BufferUtil.free(mappedBuffers[i]);
            }

View on GitHub (pinned to 6d60124e15)