aeron-io/aeron · error · AeronException

[clientId= , clientName= ] Failed to map log buffer with…

Error message

[clientId=<clientId>, clientName=<clientName>] Failed to map log buffer with registrationId=<registrationId>, channel=<channel>

What it means

logBuffers() wraps any exception encountered while memory-mapping the log buffer file for a publication/image into an AeronException carrying clientId, registrationId and channel. Mapping fails when the log file is missing, unreadable, or the term-length exceeds available memory (mmap limits). The original cause is attached as the exception cause.

Solutions

1. Verify client and driver share the same aeronDirectoryName and term-length settings (channel term-length / driver config)
2. Increase vm.max_map_count (sysctl -w vm.max_map_count=...) if 'Failed to map' is caused by mmap limits
3. Check the log file exists and is readable by the client process user/permissions
4. Inspect the wrapped cause (getCause()) for the precise mmap errno
5. Use a local filesystem (not NFS) for aeronDirectoryName

Example fix

// before
Aeron aeron = Aeron.connect(new Aeron.Context().aeronDirectoryName("/mnt/nfs/aeron"));
// after
Aeron aeron = Aeron.connect(new Aeron.Context().aeronDirectoryName("/dev/shm/aeron"));

Path logFile = Path.of(aeronDir, "log"); if (!Files.isDirectory(aeronDirPath) || !aeronDirPath.toFile().canRead()) { throw new IllegalStateException("aeron dir unreadable"); }

try { subscription = aeron.addSubscription(channel, stream); } catch (AeronException e) { if (e.getCause() != null && e.getMessage().contains("Failed to map log buffer")) { fixSharedMemoryEnv(); retryConnect(); } else { throw e; } }

When it happens

Trigger: The driver created a log file the client cannot map: file deleted prematurely, wrong aeronDirectoryName shared between client and driver, term buffer length larger than /proc/sys/vm/max_map_count allows or insufficient file descriptors, I/O errors on the C'n'C media directory.

Common situations: Driver restarted with a larger term-length while an old client config persists; running in containers with low vm.max_map_count; disk cleaned while client reconnects; NFS-mounted aeron directories where mmap behaves poorly.

Understand the failure class

Background: "open() failed", "failed to open file", "cannot create file" — what a file open error means and how to fix it — this error's family across 42 libraries.

Related errors

• failed to read link file=" + linkFile
• failed to update recording log
• UncheckedIOException while backing up recording log
• failed to read link file=
• failed to write recording

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

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/ClientConductor.java:1750

    private LogBuffers logBuffers(final long registrationId, final String logFileName, final String channel)
    {
        LogBuffers logBuffers = logBuffersByIdMap.get(registrationId);
        if (null == logBuffers)
        {
            try
            {
                logBuffers = logBuffersFactory.map(logFileName);

                if (ctx.preTouchMappedMemory())
                {
                    logBuffers.preTouch();
                }

                logBuffersByIdMap.put(registrationId, logBuffers);
            }
            catch (final Exception ex)
            {
                throw new AeronException("[clientId=" + ctx.clientId() + ", clientName=" + ctx.clientName() +
                    "] Failed to map log buffer with registrationId=" + registrationId + ", channel=" + channel, ex);
            }
        }

        logBuffers.incRef();

        return logBuffers;
    }

    private int service(final long correlationId)
    {
        int workCount = 0;

        try
        {
            workCount += checkTimeouts(nanoClock.nanoTime());
            workCount += driverEventsAdapter.receive(correlationId);
        }

View on GitHub (pinned to 6d60124e15)