{"record":{"id":"8614a9103a4fad51","repo":"aeron-io/aeron","slug":"max-position-exceeded-term-length","errorCode":null,"errorMessage":"max position exceeded: term-length=","messagePattern":"max position exceeded: term-length=","errorType":"exception","errorClass":"ClusterException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/client/AeronCluster.java","lineNumber":514,"sourceCode":"            final long position = publication.tryClaim(length, bufferClaim);\n\n            trackIngressPublicationResult(position);\n\n            if (position > 0)\n            {\n                sessionKeepAliveEncoder\n                    .wrapAndApplyHeader(bufferClaim.buffer(), bufferClaim.offset(), messageHeaderEncoder)\n                    .leadershipTermId(leadershipTermId)\n                    .clusterSessionId(clusterSessionId);\n\n                bufferClaim.commit();\n\n                return true;\n            }\n\n            if (position == Publication.MAX_POSITION_EXCEEDED)\n            {\n                throw new ClusterException(\"max position exceeded: term-length=\" + publication.termBufferLength());\n            }\n\n            if (--attempts <= 0)\n            {\n                break;\n            }\n\n            idleStrategy.idle();\n        }\n\n        return false;\n    }\n\n    /**\n     * Sends an admin request to initiate a snapshot action in the cluster. This request requires elevated privileges.\n     *\n     * @param correlationId for the request.\n     * @return {@code true} if the request was sent or {@code false} otherwise.","sourceCodeStart":496,"sourceCodeEnd":532,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/client/AeronCluster.java#L496-L532","documentation":"sendKeepAlive polls the ingress publication's position after offering a keep-alive message. When the offer returns Publication.MAX_POSITION_EXCEEDED, the publication has advanced past the maximum addressable position for its term buffers, so no further messages can be sent. The library throws ClusterException to surface that the ingress publication is unusable and must be re-established.","triggerScenarios":"Calling AeronCluster.sendKeepAlive() repeatedly on a long-lived client whose ingress publication position exceeds Long 2^46-ish max position — i.e. offering messages faster than the cluster consumes them over very long sessions, or a stuck cluster letting the position run past the limit.","commonSituations":"Long-running cluster clients (days/weeks) sending high-volume ingress without reconnecting; a paused/overloaded cluster failing to drain publications; keep-alive itself offered after the publication hit the limit.","solutions":["Close the AeronCluster client and reconnect (connect()), which creates a fresh ingress publication with a new position range.","Check cluster health — the cluster is not draining ingress if positions grow unchecked; investigate slow session/consumer handling.","Reduce ingress send rate or batch size to keep the publication position below the max.","Catch ClusterException in the keep-alive loop and treat it as a signal to re-establish the cluster session."],"exampleFix":"// before\ncluster.sendKeepAlive(); // throws ClusterException at max position\n// after\ntry { cluster.sendKeepAlive(); } catch (ClusterException e) { cluster.close(); cluster = AeronCluster.connect(ctx); }","handlingStrategy":"retry","validationCode":"if (cluster.ingressPublication().position() >= Publication.MAX_POSITION_EXCEEDED) { reconnectCluster(); }","typeGuard":null,"tryCatchPattern":"try { cluster.sendKeepAlive(); } catch (ClusterException e) { if (e.getMessage().startsWith(\"max position exceeded\")) { reconnectCluster(); } else { throw e; } }","preventionTips":["Reconnect long-lived clients periodically instead of keeping publications for weeks.","Monitor cluster consumption lag on the ingress channel.","Alert on ingress publication positions approaching the max."],"tags":["cluster","ingress","publication","capacity"],"backgroundTag":"value-out-of-range","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"}