{"record":{"id":"64a35eb1210a1dad","repo":"aeron-io/aeron","slug":"failed-to-update-recording-log","errorCode":null,"errorMessage":"failed to update recording log","messagePattern":"failed to update recording log","errorType":"exception","errorClass":"AgentTerminationException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/ClusterBackupAgent.java","lineNumber":971,"sourceCode":"                wasRecordingLogUpdated = true;\n            }\n\n            if (null != leaderLastTermEntry && recordingLog.isUnknown(leaderLastTermEntry.leadershipTermId))\n            {\n                recordingLog.appendTerm(\n                    liveLogRecordingId,\n                    leaderLastTermEntry.leadershipTermId,\n                    leaderLastTermEntry.termBaseLogPosition,\n                    leaderLastTermEntry.timestamp);\n\n                wasRecordingLogUpdated = true;\n                leaderLastTermEntry = null;\n            }\n        }\n        catch (final Exception ex)\n        {\n            ctx.countedErrorHandler().onError(ex);\n            throw new AgentTerminationException(\"failed to update recording log\");\n        }\n\n        if (wasRecordingLogUpdated)\n        {\n            recordingLog.force(2);\n            if (!snapshotsRetrieved.isEmpty())\n            {\n                ctx.snapshotRetrieveCounter().incrementRelease();\n            }\n\n            if (null != eventsListener)\n            {\n                eventsListener.onUpdatedRecordingLog(recordingLog, snapshotsRetrieved);\n            }\n        }\n\n        snapshotsRetrieved.clear();\n        snapshotsToRetrieve.clear();","sourceCodeStart":953,"sourceCodeEnd":989,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/ClusterBackupAgent.java#L953-L989","documentation":"ClusterBackupAgent throws AgentTerminationException(\"failed to update recording log\") when an unexpected exception occurs while the backup agent checks/updates the recording log during a backup cycle. The original exception is reported via the counted error handler and the agent terminates, because a consistent recording log view is essential to continue backup safely.","triggerScenarios":"Any exception thrown inside ClusterBackupAgent.doWork()'s recording-log update phase (e.g. AeronIOException reading recordings, rethrow of failures from the archive client while listing or extending recordings).","commonSituations":"Archive media failures/disk errors while querying the recording log, corrupted local recording catalog, or an archive client returning error responses mid-scan in a backup node process.","solutions":["Inspect the exception logged by countedErrorHandler just before this message for the root cause","Check disk health and archive storage on the backup node","Restart the backup node / aeron archive to rebuild a consistent recording log state","Verify archive client connectivity and versions match the cluster"],"exampleFix":"// before\n// backup agent crashes with AgentTerminationException on transient IO error\n// after\n// fix underlying storage, then restart:\n// java -Daeron.cluster.backup.progress.timeout=... io.aeron.cluster.ClusterBackup\n// and ensure the archive media is writable and healthy","handlingStrategy":"try-catch","validationCode":"// preflight: check archive reachable and disk healthy before starting backup\nif (!archiveProxy.isConnected()) throw new IllegalStateException(\"archive not connected\");","typeGuard":null,"tryCatchPattern":"try {\n    backup.start();\n} catch (AgentTerminationException e) {\n    log.error(\"backup agent terminated; check countedErrorHandler log for root cause\", e);\n    // alert ops, inspect disk/archive, then restart the backup node\n}","preventionTips":["Monitor disk health and space on backup nodes","Keep Aeron versions aligned across cluster and backup","Log countedErrorHandler output centrally for root-cause triage"],"tags":["aeron","cluster-backup","agent-termination","io"],"backgroundTag":"file-read-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"}