{"record":{"id":"1035e7921dc8d0d4","repo":"aeron-io/aeron","slug":"connection-to-the-archive-is-no-longer-available","errorCode":null,"errorMessage":"connection to the archive is no longer available","messagePattern":"connection to the archive is no longer available","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/client/ArchiveProxy.java","lineNumber":1488,"sourceCode":"        retryIdleStrategy.reset();\n\n        int attempts = retryAttempts;\n        while (true)\n        {\n            final long position = publication.offer(buffer, 0, MessageHeaderEncoder.ENCODED_LENGTH + length);\n            if (position > 0)\n            {\n                return true;\n            }\n\n            if (position == Publication.CLOSED)\n            {\n                throw new ArchiveException(\"connection to the archive has been closed\");\n            }\n\n            if (position == Publication.NOT_CONNECTED)\n            {\n                throw new ArchiveException(\"connection to the archive is no longer available\");\n            }\n\n            if (position == Publication.MAX_POSITION_EXCEEDED)\n            {\n                throw new ArchiveException(\n                    \"offer failed due to max position being reached: term-length=\" + publication.termBufferLength());\n            }\n\n            if (--attempts <= 0)\n            {\n                return false;\n            }\n\n            retryIdleStrategy.idle();\n        }\n    }\n\n    private boolean offerWithTimeout(final int length, final AgentInvoker aeronClientInvoker)","sourceCodeStart":1470,"sourceCodeEnd":1506,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/client/ArchiveProxy.java#L1470-L1506","documentation":"ArchiveProxy.offer() throws this ArchiveException when the control publication's offer() returned Publication.NOT_CONNECTED, meaning the control-request channel to the archive no longer has an active subscriber connection. The archive side (or the intermediary) has dropped the image, so the command cannot be enqueued. It is thrown eagerly from offer() rather than silently returning false so the caller fails fast with a diagnosable error.","triggerScenarios":"Any ArchiveProxy command that sends a control message — keepAlive, closeSession, startRecording, stopRecording, stopRecordingByIdentity, stopReplay — when the underlying control publication reports NOT_CONNECTED on offer (archive process stopped/restarted, archive session closed, or network partition removing the connected image).","commonSituations":"The Aeron Archive server was shut down or crashed between establishing the client and issuing a command; an idle keepAlive raced with session expiry; the archive client's control publication lost its destination connectivity (e.g. archive restarted without the client reconnecting).","solutions":["Check that the Aeron Archive process is running and reachable on the configured control channel before issuing commands","Reconnect the archive client (close and recreate AeronArchive / re-establish the control session) after this error","Verify keepAlive interval is shorter than the archive's session timeout so the session is not dropped","Inspect network/firewall stability between client and archive control-request/replay channels"],"exampleFix":"// before\narchiveProxy.startRecording(channel, streamId, LOCAL);\n\n// after\nif (archive == null || archiveArchiveClientIsStale) {\n    aeronArchive.close();\n    aeronArchive = AeronArchive.connect(ctx); // re-establish control session\n}\naeronArchive.startRecording(channel, streamId, LOCAL);","handlingStrategy":"retry","validationCode":"if (controlPublication.isConnected()) { proxyCommand(...); } else { reconnectArchiveClient(); }","typeGuard":"boolean archiveControlConnected(ExclusivePublication p) { return p != null && !p.isClosed() && p.isConnected(); }","tryCatchPattern":"try {\n    archiveProxy.startRecording(channel, streamId, LOCAL);\n} catch (ArchiveException e) {\n    if (e.getMessage().contains(\"no longer available\")) {\n        reconnectArchive(); // recreate AeronArchive session\n    }\n}","preventionTips":["Send keepAlive at an interval well below the archive session timeout","Monitor publication.isConnected()/isClosed() before sending commands","Wrap archive clients in a reconnect-on-failure wrapper","Alert on archive process health to catch outages before clients fail"],"tags":["aeron-archive","connection","control-channel","rpc"],"backgroundTag":"connection-refused","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}