{"record":{"id":"01d52bc34a562a29","repo":"aeron-io/aeron","slug":"local-archive-not-connected","errorCode":null,"errorMessage":"local archive not connected","messagePattern":"local archive not connected","errorType":"exception","errorClass":"AgentTerminationException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/ClusterBackupAgent.java","lineNumber":1092,"sourceCode":"                    }\n                    else\n                    {\n                        throw ex;\n                    }\n                }\n                else if (RecordingSignalEventDecoder.TEMPLATE_ID == templateId && null != snapshotReplication)\n                {\n                    snapshotReplication.onSignal(\n                        poller.correlationId(),\n                        poller.recordingId(),\n                        poller.recordingPosition(),\n                        poller.recordingSignal());\n                }\n            }\n            else if (0 == workCount && !poller.subscription().isConnected())\n            {\n                ctx.countedErrorHandler().onError(new ClusterEvent(\"local archive not connected\"));\n                throw new AgentTerminationException();\n            }\n        }\n\n        return workCount;\n    }\n\n    private long startLogRecording()\n    {\n        final RecordingLog.Entry logEntry = recordingLog.findLastTerm();\n        final int streamId = ctx.logStreamId();\n        final long recordingSubscriptionId = null == logEntry ?\n            backupArchive.startRecording(recordingChannel, streamId, REMOTE, true) :\n            backupArchive.extendRecording(logEntry.recordingId, recordingChannel, streamId, REMOTE, true);\n\n        CloseHelper.close(ctx.countedErrorHandler(), recordingSubscription);\n        recordingChannel = null;\n        recordingSubscription = null;\n","sourceCodeStart":1074,"sourceCodeEnd":1110,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/ClusterBackupAgent.java#L1074-L1110","documentation":"Thrown when, in a doWork cycle, no work was done and the backup agent's subscription to the local archive control channel is not connected, meaning the archive is unreachable. The agent reports a ClusterEvent and throws AgentTerminationException since backup cannot progress.","triggerScenarios":"poller.subscription().isConnected() is false while polling the local archive during backup, with zero work done in that cycle.","commonSituations":"Local Aeron Archive process not running on the backup node, wrong control channel/ports in cluster backup config, firewall blocking UDP/TCP control endpoints.","solutions":["Verify the local archive is running and its control-channel endpoint matches aeron.archive.control.channel in backup config","Check network/firewall rules for the control channel ports","Validate archive client and archive server versions match","Restart the archive and then the cluster backup node"],"exampleFix":"// before\n.archiveControlChannel(\"aeron:udp?endpoint=localhost:0\") // invalid\n// after\n.archiveControlChannel(\"aeron:udp?endpoint=localhost:9010\")\n// and ensure the archive is started before the backup agent","handlingStrategy":"retry","validationCode":"// before starting backup, confirm the local archive control channel is reachable\nif (!archiveControlSubscription.isConnected()) {\n    throw new IllegalStateException(\"local archive not reachable on control channel\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    backupAgent.doWork();\n} catch (AgentTerminationException e) {\n    // archive not connected: backoff and retry with restart of archive\n}","preventionTips":["Start the local archive before the cluster backup agent","Pin archive control channel endpoints in config and verify with netstat","Add connectivity monitoring for archive control ports","Match archive client/server versions"],"tags":["aeron","network","archive","connectivity"],"backgroundTag":"connection-refused","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}