aeron-io/aeron · error · ArchiveException

failed to send keep alive after archive connect

Error message

failed to send keep alive after archive connect

What it means

Thrown by the AeronArchive connect state machine after the control session is established: the client could not offer a keep-alive message on the archive control request publication. Without a keep-alive the archive would eventually time out and close the new session, so the connect fails fast. This is an I/O/publication failure, not a logical error.

Solutions

  1. Retry AeronArchive.connect() after confirming the archive is up and reachable
  2. Verify controlRequestChannel/controlRequestStreamId in AeronArchive.Context point at the running archive's control endpoint
  3. Check archive logs for session rejection or shutdown around the connect time
  4. Check network connectivity and that the control-request publication is not closed by a driver error

Example fix

// before
AeronArchive archive = AeronArchive.connect(); // throws if transport hiccups
// after
AeronArchive archive;
try {
    archive = AeronArchive.connect();
} catch (ArchiveException e) {
    // backoff and retry connect
    archive = retryConnect(3);
}
Defensive patterns

Strategy: retry

Validate before calling

// check archive reachability before connect
if (!isPortOpen(archiveHost, archiveControlPort)) throw new IllegalStateException("archive control endpoint unreachable");

Try / catch

try { archive = AeronArchive.connect(ctx); } catch (ArchiveException e) { backoffAndRetry(e); }

Prevention

When it happens

Trigger: Calling AeronArchive.connect() (or asyncConnect completion) when the control request Publication offer fails because the publication is CLOSED or NOT_CONNECTED — e.g. the archive rejected the connection or the control channel died between session establishment and keep-alive.

Common situations: Archive process restarted mid-connect; control-response channel reached but control-request publication lost connection (wrong channel, multicast/TTL issues); network partition during connect; archive shut down by operator or crashed.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

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

Appendix: source

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

                            state(State.SEND_ARCHIVE_ID_REQUEST);
                        }
                    }
                }
            }
        }

        private void state(final State newState)
        {
//            System.out.println(state + " -> " + newState);
            state = newState;
        }

        private AeronArchive transitionToDone(final long archiveId)
        {
            if (!archiveProxy.keepAlive(controlSessionId, NULL_VALUE))
            {
                archiveProxy.closeSession(controlSessionId);
                throw new ArchiveException("failed to send keep alive after archive connect");
            }

            final AeronArchive aeronArchive = new AeronArchive(
                ctx, controlResponsePoller, archiveProxy, controlSessionId, archiveId);

            state(State.DONE);
            return aeronArchive;
        }
    }

    static Exception quietClose(final Exception previousException, final AutoCloseable closeable)
    {
        Exception resultException = previousException;
        if (null != closeable)
        {
            try
            {
                closeable.close();

View on GitHub (pinned to 6d60124e15)