{"record":{"id":"59a56392bb915a14","repo":"aeron-io/aeron","slug":"uncheckedioexception-while-updating-recording-log","errorCode":null,"errorMessage":"UncheckedIOException while updating recording log","messagePattern":"UncheckedIOException while updating recording log","errorType":"exception","errorClass":"UncheckedIOException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/ClusterToolOperator.java","lineNumber":1423,"sourceCode":"                        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    }\n}\n","sourceCodeStart":1405,"sourceCodeEnd":1427,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/ClusterToolOperator.java#L1405-L1427","documentation":"ClusterToolOperator.updateRecordingLog atomically replaces the recording log: it deletes the old file and moves the newly written one into place. Any IOException in that block is wrapped in UncheckedIOException with this message. It indicates the recording log could not be updated at the filesystem level.","triggerScenarios":"Any ClusterTool operation that calls updateRecordingLog where Files.delete(recordingLog) or Files.move(newRecordingLog, recordingLog) throws IOException (permissions, file locked, missing temp file, cross-filesystem move failure).","commonSituations":"Read-only or full-disk cluster directory; recording log locked by a running cluster node; the temp newRecordingLog was never created because an earlier step failed; permission differences between the tool user and the node user.","solutions":["Stop the cluster node so the recording log is not held open/locked, then rerun the tool.","Check write permissions on the cluster directory for the tool's user.","Ensure sufficient disk space and a healthy filesystem (delete+move require writable directory).","Inspect the UncheckedIOException cause to identify whether delete or move failed and fix that specific path."],"exampleFix":"// before\ntool.recordingLogAction(clusterDir, ...); // fails: node still running holds file\n// after\n// 1) stop the node  2) rerun tool  3) restart node\nclusterNode.stop();\ntool.recordingLogAction(clusterDir, ...);\nclusterNode.start();","handlingStrategy":"try-catch","validationCode":"Path recordingLog = clusterDir.toPath().resolve(\"recording.log\");\nif (!Files.isWritable(recordingLog.getParent()))\n{\n    throw new IllegalStateException(\"cluster dir not writable: \" + recordingLog.getParent());\n}","typeGuard":null,"tryCatchPattern":"try\n{\n    tool.recordingLogAction(clusterDir, ...);\n}\ncatch (UncheckedIOException ex)\n{\n    // cause tells whether Files.delete or Files.move failed\n    ex.getCause().printStackTrace();\n}","preventionTips":["Stop the cluster node before rewriting the recording log so files are not locked.","Keep the cluster directory and temp file on the same filesystem (atomic move).","Run tools with adequate directory write permissions."],"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"}