aeron-io/aeron · error · AgentTerminationException

local archive not connected

Error message

local archive not connected

What it means

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.

Solutions

1. Verify the local archive is running and its control-channel endpoint matches aeron.archive.control.channel in backup config
2. Check network/firewall rules for the control channel ports
3. Validate archive client and archive server versions match
4. Restart the archive and then the cluster backup node

Example fix

// before
.archiveControlChannel("aeron:udp?endpoint=localhost:0") // invalid
// after
.archiveControlChannel("aeron:udp?endpoint=localhost:9010")
// and ensure the archive is started before the backup agent

// before starting backup, confirm the local archive control channel is reachable
if (!archiveControlSubscription.isConnected()) {
    throw new IllegalStateException("local archive not reachable on control channel");
}

try {
    backupAgent.doWork();
} catch (AgentTerminationException e) {
    // archive not connected: backoff and retry with restart of archive
}

When it happens

Trigger: poller.subscription().isConnected() is false while polling the local archive during backup, with zero work done in that cycle.

Common situations: Local Aeron Archive process not running on the backup node, wrong control channel/ports in cluster backup config, firewall blocking UDP/TCP control endpoints.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• archive is not connected
• failed to fetch remote recording descriptor
• failed to resolve subscription endpoint: channel=" +…
• failed to send bounded replay request
• failed to send replay request

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

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/ClusterBackupAgent.java:1092

                    }
                    else
                    {
                        throw ex;
                    }
                }
                else if (RecordingSignalEventDecoder.TEMPLATE_ID == templateId && null != snapshotReplication)
                {
                    snapshotReplication.onSignal(
                        poller.correlationId(),
                        poller.recordingId(),
                        poller.recordingPosition(),
                        poller.recordingSignal());
                }
            }
            else if (0 == workCount && !poller.subscription().isConnected())
            {
                ctx.countedErrorHandler().onError(new ClusterEvent("local archive not connected"));
                throw new AgentTerminationException();
            }
        }

        return workCount;
    }

    private long startLogRecording()
    {
        final RecordingLog.Entry logEntry = recordingLog.findLastTerm();
        final int streamId = ctx.logStreamId();
        final long recordingSubscriptionId = null == logEntry ?
            backupArchive.startRecording(recordingChannel, streamId, REMOTE, true) :
            backupArchive.extendRecording(logEntry.recordingId, recordingChannel, streamId, REMOTE, true);

        CloseHelper.close(ctx.countedErrorHandler(), recordingSubscription);
        recordingChannel = null;
        recordingSubscription = null;

View on GitHub (pinned to 6d60124e15)