{"record":{"id":"48a707ad7910e905","repo":"aeron-io/aeron","slug":"failed-to-write-recording","errorCode":null,"errorMessage":"failed to write recording","messagePattern":"failed to write recording","errorType":"exception","errorClass":"ClusterException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/ClusterToolOperator.java","lineNumber":1407,"sourceCode":"            }\n            else\n            {\n                final Path newRecordingLog = clusterDir.toPath().resolve(RecordingLog.RECORDING_LOG_FILE_NAME + \".tmp\");\n                Files.deleteIfExists(newRecordingLog);\n                final ByteBuffer byteBuffer =\n                    ByteBuffer.allocateDirect(RecordingLog.MAX_ENTRY_LENGTH).order(LITTLE_ENDIAN);\n                final UnsafeBuffer buffer = new UnsafeBuffer(byteBuffer);\n                try (FileChannel fileChannel = FileChannel.open(newRecordingLog, CREATE_NEW, WRITE))\n                {\n                    long position = 0;\n                    for (final RecordingLog.Entry e : entries)\n                    {\n                        RecordingLog.writeEntryToBuffer(e, buffer);\n                        byteBuffer.limit(e.length()).position(0);\n\n                        if (e.length() != fileChannel.write(byteBuffer, position))\n                        {\n                            throw new ClusterException(\"failed to write recording\");\n                        }\n                        position += e.length();\n                    }\n                }\n                finally\n                {\n                    BufferUtil.free(byteBuffer);\n                }\n\n                Files.delete(recordingLog);\n                Files.move(newRecordingLog, recordingLog);\n            }\n        }\n        catch (final IOException ex)\n        {\n            throw new UncheckedIOException(ex);\n        }\n    }","sourceCodeStart":1389,"sourceCodeEnd":1425,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/ClusterToolOperator.java#L1389-L1425","documentation":"When rewriting the recording log, ClusterToolOperator writes each entry into a ByteBuffer and calls fileChannel.write at the target position, verifying the return value equals the entry length. A short write throws ClusterException(\"failed to write recording\"). This guards against partial writes corrupting the recording log.","triggerScenarios":"Running a ClusterTool operation that rewrites the recording log file where FileChannel.write returns fewer bytes than the entry length (disk full, I/O error, underlying storage issue).","commonSituations":"Disk full or quota exceeded on the volume holding the cluster directory; filesystem errors (ENOSPC, EIO); writing to a network mount that drops writes; concurrent modification of the recording log.","solutions":["Free disk space on the filesystem holding the recording log and retry the operation.","Check filesystem health (dmesg / mount status) for I/O errors on the storage device.","Ensure no other process is writing to the recording log concurrently; run tools on a quiescent node.","Retry the tool command after resolving the storage issue; verify the recording log with ClusterTool.describeRecordingLog."],"exampleFix":"// before\ntool.recordingLogAction(clusterDir, ...); // fails on full disk\n// after\ndf -h /var/aeron/cluster  # ensure free space first\ntool.recordingLogAction(clusterDir, ...);","handlingStrategy":"retry","validationCode":"// before tool operation\nFile clusterDir = new File(dirArg);\nif (clusterDir.getFreeSpace() < MIN_REQUIRED_BYTES)\n{\n    throw new IllegalStateException(\"insufficient disk space for recording log rewrite\");\n}","typeGuard":null,"tryCatchPattern":"try\n{\n    tool.recordingLogAction(clusterDir, ...);\n}\ncatch (ClusterException ex)\n{\n    if (!\"failed to write recording\".equals(ex.getMessage())) throw ex;\n    // free space / fix storage, then retry once\n}","preventionTips":["Monitor disk space where the recording log lives.","Run recording log operations only on quiescent (stopped or not-leader) nodes.","Use local, healthy storage rather than flaky network mounts for cluster dirs."],"tags":["aeron","cluster","io","filesystem"],"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-16T04:17:20.429Z"}