{"record":{"id":"0ddb408dc847855e","repo":"aeron-io/aeron","slug":"unexpected-loss-of-connection-to-cluster","errorCode":null,"errorMessage":"unexpected loss of connection to cluster","messagePattern":"unexpected loss of connection to cluster","errorType":"exception","errorClass":"ClusterException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/client/AeronCluster.java","lineNumber":2482,"sourceCode":"                .version(Configuration.PROTOCOL_SEMANTIC_VERSION)\n                .responseChannel(responseChannel)\n                .putEncodedCredentials(encodedCredentials, 0, encodedCredentials.length)\n                .clientInfo(clientInfo);\n\n            messageLength = MessageHeaderEncoder.ENCODED_LENGTH + encoder.encodedLength();\n            state(State.SEND_MESSAGE);\n        }\n\n        private void sendMessage()\n        {\n            final long position = ingressPublication.offer(buffer, 0, messageLength);\n            if (position > 0)\n            {\n                state(State.POLL_RESPONSE);\n            }\n            else if (Publication.CLOSED == position || Publication.NOT_CONNECTED == position)\n            {\n                throw new ClusterException(\"unexpected loss of connection to cluster\");\n            }\n        }\n\n        private void pollResponse()\n        {\n            if (egressPoller.poll() > 0 &&\n                egressPoller.isPollComplete() &&\n                egressPoller.correlationId() == correlationId)\n            {\n                if (egressPoller.isChallenged())\n                {\n                    correlationId = NULL_VALUE;\n                    clusterSessionId = egressPoller.clusterSessionId();\n                    prepareChallengeResponse(ctx.credentialsSupplier().onChallenge(egressPoller.encodedChallenge()));\n                    return;\n                }\n\n                switch (egressPoller.eventCode())","sourceCodeStart":2464,"sourceCodeEnd":2500,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/client/AeronCluster.java#L2464-L2500","documentation":"During connect()'s AWAIT_CONNECTED/SEND state, the client publishes a connect request and checks the publication position. If the publication returns CLOSED or NOT_CONNECTED the client's publication is dead, so connect aborts with ClusterException('unexpected loss of connection to cluster').","triggerScenarios":"The ingress publication closes because the cluster is down/unreachable, ingressEndpoints are wrong, or the destination died after the client started connecting.","commonSituations":"Cluster nodes not running or wrong ingress endpoint/port; firewall or network drop; cluster leader change during connect leaving the publication closed; driver (MediaDriver) restarted mid-connect.","solutions":["Verify cluster members are running and ingressEndpoints/ingressChannel point at live nodes","Check MediaDriver is running and Aeron directories are healthy; restart driver and client","Retry AeronCluster.connect() with backoff; add retransient connect logic around bootstrap","Inspect cluster node logs and ingress endpoint configuration for mismatched endpoints"],"exampleFix":"// before\nAeronCluster cluster = AeronCluster.connect(ctx); // fails if cluster temporarily down\n// after\nAeronCluster cluster = null;\nfor (int i = 0; i < 5 && cluster == null; i++) {\n    try { cluster = AeronCluster.connect(ctx); }\n    catch (ClusterException e) { sleepBackoff(i); }\n}","handlingStrategy":"retry","validationCode":"// before connecting, sanity-check ingress endpoints resolve\nfor (String ep : ingressEndpoints.split(\",\")) { /* verify host:port reachable */ }","typeGuard":null,"tryCatchPattern":"try {\n    AeronCluster cluster = AeronCluster.connect(ctx);\n} catch (ClusterException e) {\n    if (e.getMessage().contains(\"unexpected loss of connection\")) {\n        // retry with backoff after checking cluster/driver health\n    } else {\n        throw e;\n    }\n}","preventionTips":["Monitor cluster member health and leader status before client bootstrap","Keep MediaDriver alive; avoid restarting the driver mid-connect","Use bounded retries with exponential backoff around connect()","Verify ingress endpoint addresses/ports against cluster config"],"tags":["network","cluster-client","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"}