aeron-io/aeron · error · UncheckedIOException

UncheckedIOException while updating recording log

Error message

UncheckedIOException while updating recording log

What it means

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.

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.

Example fix

// before
tool.recordingLogAction(clusterDir, ...); // fails: node still running holds file
// after
// 1) stop the node  2) rerun tool  3) restart node
clusterNode.stop();
tool.recordingLogAction(clusterDir, ...);
clusterNode.start();

Defensive patterns

Strategy: try-catch

Validate before calling

Path recordingLog = clusterDir.toPath().resolve("recording.log");
if (!Files.isWritable(recordingLog.getParent()))
{
    throw new IllegalStateException("cluster dir not writable: " + recordingLog.getParent());
}

Try / catch

try
{
    tool.recordingLogAction(clusterDir, ...);
}
catch (UncheckedIOException ex)
{
    // cause tells whether Files.delete or Files.move failed
    ex.getCause().printStackTrace();
}

Prevention

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.

When it happens

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

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

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/59a56392bb915a14. Report an issue: GitHub.

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/ClusterToolOperator.java:1423

                        if (e.length() != fileChannel.write(byteBuffer, position))
                        {
                            throw new ClusterException("failed to write recording");
                        }
                        position += e.length();
                    }
                }
                finally
                {
                    BufferUtil.free(byteBuffer);
                }

                Files.delete(recordingLog);
                Files.move(newRecordingLog, recordingLog);
            }
        }
        catch (final IOException ex)
        {
            throw new UncheckedIOException(ex);
        }
    }
}

View on GitHub (pinned to 6d60124e15)