{"record":{"id":"19a6fc5384fb168a","repo":"aeron-io/aeron","slug":"clientid-clientid-clientname-clientname-failed-to-map-log","errorCode":null,"errorMessage":"[clientId=<clientId>, clientName=<clientName>] Failed to map log buffer with registrationId=<registrationId>, channel=<channel>","messagePattern":"\\[clientId=<clientId>, clientName=<clientName>\\] Failed to map log buffer with registrationId=<registrationId>, channel=<channel>","errorType":"exception","errorClass":"AeronException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/ClientConductor.java","lineNumber":1750,"sourceCode":"    private LogBuffers logBuffers(final long registrationId, final String logFileName, final String channel)\n    {\n        LogBuffers logBuffers = logBuffersByIdMap.get(registrationId);\n        if (null == logBuffers)\n        {\n            try\n            {\n                logBuffers = logBuffersFactory.map(logFileName);\n\n                if (ctx.preTouchMappedMemory())\n                {\n                    logBuffers.preTouch();\n                }\n\n                logBuffersByIdMap.put(registrationId, logBuffers);\n            }\n            catch (final Exception ex)\n            {\n                throw new AeronException(\"[clientId=\" + ctx.clientId() + \", clientName=\" + ctx.clientName() +\n                    \"] Failed to map log buffer with registrationId=\" + registrationId + \", channel=\" + channel, ex);\n            }\n        }\n\n        logBuffers.incRef();\n\n        return logBuffers;\n    }\n\n    private int service(final long correlationId)\n    {\n        int workCount = 0;\n\n        try\n        {\n            workCount += checkTimeouts(nanoClock.nanoTime());\n            workCount += driverEventsAdapter.receive(correlationId);\n        }","sourceCodeStart":1732,"sourceCodeEnd":1768,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/ClientConductor.java#L1732-L1768","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify client and driver share the same aeronDirectoryName and term-length settings (channel term-length / driver config)","Increase vm.max_map_count (sysctl -w vm.max_map_count=...) if 'Failed to map' is caused by mmap limits","Check the log file exists and is readable by the client process user/permissions","Inspect the wrapped cause (getCause()) for the precise mmap errno","Use a local filesystem (not NFS) for aeronDirectoryName"],"exampleFix":"// before\nAeron aeron = Aeron.connect(new Aeron.Context().aeronDirectoryName(\"/mnt/nfs/aeron\"));\n// after\nAeron aeron = Aeron.connect(new Aeron.Context().aeronDirectoryName(\"/dev/shm/aeron\"));","handlingStrategy":"validation","validationCode":"Path logFile = Path.of(aeronDir, \"log\"); if (!Files.isDirectory(aeronDirPath) || !aeronDirPath.toFile().canRead()) { throw new IllegalStateException(\"aeron dir unreadable\"); }","typeGuard":null,"tryCatchPattern":"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; } }","preventionTips":["Use local/tmpfs storage for aeronDirectoryName, not NFS","Align client and driver term-length and directory config","Raise vm.max_map_count in containers handling many streams"],"tags":["aeron","mmap","shared-memory","io"],"backgroundTag":"file-open-failed","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}