aeron-io/aeron · error · ArchiveException

not connected

Error message

not connected

What it means

AeronArchive's control-response poller detects that the control session is no longer connected and raises ArchiveException(NOT_CONNECTED_MSG). If the client has a context errorHandler, the error is delivered there instead of being thrown. It indicates the archive control channel connection was lost, so requests cannot be serviced.

Solutions

1. Verify the archive is running and reachable at the configured control channel before issuing requests
2. Wait for connection: AeronArchive.connect() retries internally; ensure the control channel URI (aeron.dir, control endpoints) matches the archive's configuration
3. Catch ArchiveException and reconnect via AeronArchive.connect() with an errorHandler to receive not-connected notifications instead of thrown exceptions

Example fix

// before
AeronArchive archive = AeronArchive.connect(new AeronArchive.Context().aeronDirectoryName(aeronDir));
archive.startRecording(channel, streamId, SourceLocation.LOCAL); // throws if control session dropped
// after
AeronArchive archive = AeronArchive.connect(new AeronArchive.Context()
    .aeronDirectoryName(aeronDir)
    .errorHandler(ex -> log.warn("archive not connected", ex)));
if (archive.controlSessionId() != -1) archive.startRecording(channel, streamId, SourceLocation.LOCAL);

// ensure control channel publications/subscription are connected before use
// e.g. check archiveProxy.controlPublication().isConnected() and controlResponsePoller subscription isConnected()

try {
    archiveProxyOrClient.doArchiveCall();
} catch (ArchiveException ex) {
    if (ArchiveException.NOT_CONNECTED_MSG.equals(ex.getMessage())) {
        archive = AeronArchive.connect(ctx); // re-establish session
    }
}

When it happens

Trigger: Calling any AeronArchive API (addRecordedPublication, startRecording, pollForResponse, etc.) while the underlying control subscription/publication is not connected — e.g. the archive process is down, the control channel URI is wrong, or the session has been closed/timed out.

Common situations: Archive agent not running or crashed; control-request channel misconfigured (wrong endpoint/host); archive restarted and the client session invalidated; network partition between client and archive.

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

• ControlSession.RESPONSE_NOT_CONNECTED_MSG + ": " + session
• failed to send replay request
• failed get acknowledgement of replay request to: " +…
• failed get replay image for sessionId=" +…
• failed to send invalidate recording request

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

Appendix: source

Thrown at aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java:512

     */
    public void checkForErrorResponse()
    {
        lock.lock();
        try
        {
            ensureConnected();

            final ControlResponsePoller poller = controlResponsePoller;
            if (!poller.subscription().isConnected())
            {
                state(State.DISCONNECTED);
                if (null != context.errorHandler())
                {
                    context.errorHandler().onError(new ArchiveException(NOT_CONNECTED_MSG));
                }
                else
                {
                    throw new ArchiveException(NOT_CONNECTED_MSG);
                }
            }
            else if (poller.poll() != 0 && poller.isPollComplete())
            {
                if (poller.controlSessionId() == controlSessionId)
                {
                    if (poller.code() == ControlResponseCode.ERROR)
                    {
                        final ArchiveException ex = new ArchiveException(
                            poller.errorMessage(),
                            (int)poller.relevantId(),
                            poller.correlationId());

                        if (null != context.errorHandler())
                        {
                            context.errorHandler().onError(ex);
                        }
                        else

View on GitHub (pinned to 6d60124e15)