aeron-io/aeron · error · UncheckedIOException

UncheckedIOException while backing up recording log

Error message

UncheckedIOException while backing up recording log

What it means

During seedRecordingLogFromSnapshot, ClusterToolOperator copies a snapshot into the recording log backup and, if an IOException occurs while backing up the recording log, wraps it in an UncheckedIOException with this message. It signals filesystem-level failure while seeding the recording log from a snapshot.

Solutions

1. Check disk space and that the cluster directory is writable by the user running the tool.
2. Verify the source recording log / snapshot files exist and are readable.
3. Close other processes holding locks on the cluster directory (other cluster nodes, backup jobs).
4. Catch the UncheckedIOException and inspect the wrapped IOException's cause for the specific OS error.

Example fix

// before
try (Stream<Path> ignored = Files.list(clusterDir)) { tool.seedRecordingLogFromSnapshot(...); } // fails with UncheckedIOException
// after
try
{
    tool.seedRecordingLogFromSnapshot(...);
}
catch (UncheckedIOException ex)
{
    System.err.println("backup failed: " + ex.getCause()); // inspect underlying IOException
}

// before running the tool
Path clusterDir = Paths.get(clusterDirArg);
if (!Files.isDirectory(clusterDir) || !Files.isWritable(clusterDir)) {
    throw new IllegalStateException("cluster dir missing or not writable: " + clusterDir);
}

try
{
    operator.seedRecordingLogFromSnapshot(clusterDir, ...);
}
catch (UncheckedIOException ex)
{
    IOException cause = ex.getCause();
    // log cause, fix permissions/disk, retry
}

When it happens

Trigger: Running a ClusterTool operation (e.g. recover/snapshot seeding) where the code attempts to copy files to recordingLogBackup with REPLACE_EXISTING/COPY_ATTRIBUTES and the underlying file operations raise IOException (missing source, bad permissions, full disk).

Common situations: Cluster directory on a read-only or full filesystem; the recording log backup file locked by another process; running the tool as a user without write permission to the cluster directory; corrupted cluster dir missing expected files.

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

• failed to write recording
• UncheckedIOException while updating recording log
• failed to read link file=
• failed to read link file=" + linkFile
• [clientId= , clientName= ] Failed to map log buffer with…

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

Appendix: source

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

                {
                    snapshotIndex = i;
                    break;
                }
            }
        }

        final Path recordingLogBackup = clusterDir.toPath().resolve(RecordingLog.RECORDING_LOG_FILE_NAME + ".bak");
        try
        {
            Files.copy(
                clusterDir.toPath().resolve(RecordingLog.RECORDING_LOG_FILE_NAME),
                recordingLogBackup,
                REPLACE_EXISTING,
                COPY_ATTRIBUTES);
        }
        catch (final IOException ex)
        {
            throw new UncheckedIOException(ex);
        }

        if (Aeron.NULL_VALUE == snapshotIndex)
        {
            updateRecordingLog(clusterDir, Collections.emptyList());
        }
        else
        {
            final List<RecordingLog.Entry> truncatedEntries = new ArrayList<>();
            int serviceId = ConsensusModule.Configuration.SERVICE_ID;
            for (int i = snapshotIndex; i >= 0; i--)
            {
                final RecordingLog.Entry entry = entries.get(i);
                if (RecordingLog.isValidSnapshot(entry) && entry.serviceId == serviceId)
                {
                    truncatedEntries.add(new RecordingLog.Entry(
                        entry.recordingId,
                        entry.leadershipTermId,

View on GitHub (pinned to 6d60124e15)