{"record":{"id":"d0b277ff7c68a422","repo":"aeron-io/aeron","slug":"publication-at-max-position-term-length-termbufferlength","errorCode":null,"errorMessage":"publication at max position: term-length=${termBufferLength}","messagePattern":"publication at max position: term-length=(.+?)","errorType":"exception","errorClass":"ClusterException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/ConsensusPublisher.java","lineNumber":629,"sourceCode":"        standbySnapshotEncoder\n            .responseChannel(responseChannel)\n            .putEncodedCredentials(encodedCredentials, 0, encodedCredentials.length);\n\n        final int encodedLength = MessageHeaderEncoder.ENCODED_LENGTH + standbySnapshotEncoder.encodedLength();\n\n        return sendPublication(publication, buffer, encodedLength);\n    }\n\n    private static void checkResult(final long position, final Publication publication)\n    {\n        if (Publication.CLOSED == position)\n        {\n            throw new ClusterException(\"publication is closed\");\n        }\n\n        if (Publication.MAX_POSITION_EXCEEDED == position)\n        {\n            throw new ClusterException(\"publication at max position: term-length=\" + publication.termBufferLength());\n        }\n    }\n\n    private static boolean sendPublication(\n        final ExclusivePublication publication,\n        final ExpandableArrayBuffer buffer,\n        final int length)\n    {\n        int attempts = SEND_ATTEMPTS;\n        do\n        {\n            final long position = publication.offer(buffer, 0, length);\n            if (position > 0)\n            {\n                return true;\n            }\n\n            checkResult(position, publication);","sourceCodeStart":611,"sourceCodeEnd":647,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/ConsensusPublisher.java#L611-L647","documentation":"checkResult throws when a publication offer returns MAX_POSITION_EXCEEDED. The term buffer for the consensus publication is full at its maximum position, meaning consumers stopped draining it far behind the producer position.","triggerScenarios":"offer(...) on any consensus publication (canvassPosition, requestVote, placeVote, newLeadershipTerm, appendPosition, commitPosition) returns Publication.MAX_POSITION_EXCEEDED — the publication's image reached its max position because subscribers (peer members) are not consuming.","commonSituations":"A peer cluster member stalled or dead so nobody drains its consensus subscription; term buffer length too small for message volume; long GC pauses on a follower letting positions run away.","solutions":["Fix or restart the member whose consensus subscription is not consuming","Increase consensus channel term length (term-length URI param) if flow control demands it","Enable/rely on flow control (min/min-ticks) so the leader does not outrun the slowest member indefinitely","Verify network connectivity and that the follower is not blocked (disk, GC)"],"exampleFix":"// before: leader outrunning a stalled follower\nClusterException: publication at max position: term-length=65536\n// after\nAeronCluster consensus channel URI: aeron:udp?endpoint=...|term-length=1m|fc=min","handlingStrategy":"retry","validationCode":"// Monitor consumer position vs producer position before sending\nif (publication.position() - publication.consumerPosition() > threshold) { /* back off, investigate subscriber */ }","typeGuard":null,"tryCatchPattern":"try {\n    publisher.appendPosition(...);\n} catch (ClusterException e) {\n    if (e.getMessage().startsWith(\"publication at max position\")) {\n        // restart the stalled member, then re-offer with backoff\n    } else { throw e; }\n}","preventionTips":["Size term-length appropriately for consensus message volume","Monitor followers for consumption stalls (disk, GC)","Use flow control so the leader paces to members"],"tags":["aeron","cluster","publication","backpressure"],"backgroundTag":"rate-limit-exceeded","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"}