{"record":{"id":"d3d810eab9fd88d1","repo":"aeron-io/aeron","slug":"log-publication-at-max-position-term-length-termbufferlength","errorCode":null,"errorMessage":"log publication at max position: term-length=${termBufferLength}","messagePattern":"log publication at max position: term-length=(.+?)","errorType":"exception","errorClass":"ClusterException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/LogPublisher.java","lineNumber":330,"sourceCode":"            }\n\n            checkResult(position, publication);\n        }\n        while (--attempts > 0);\n\n        return false;\n    }\n\n    private static void checkResult(final long position, final Publication publication)\n    {\n        if (Publication.CLOSED == position)\n        {\n            throw new ClusterException(\"log publication is closed\");\n        }\n\n        if (Publication.MAX_POSITION_EXCEEDED == position)\n        {\n            throw new ClusterException(\n                \"log publication at max position: term-length=\" + publication.termBufferLength());\n        }\n    }\n\n    /**\n     * {@inheritDoc}\n     */\n    @Override\n    public String toString()\n    {\n        return \"LogPublisher{\" +\n            \"destinationChannel='\" + destinationChannel + '\\'' +\n            '}';\n    }\n}\n","sourceCodeStart":312,"sourceCodeEnd":346,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/LogPublisher.java#L312-L346","documentation":"LogPublisher.checkResult also detects Publication.MAX_POSITION_EXCEEDED: an append would have gone past the maximum position allowed by the term buffer length. Aeron refuses to offer beyond the position limit, so the publisher throws a ClusterException reporting the term buffer length.","triggerScenarios":"Appending to the cluster log when the current position is at/near the maximum representable for the configured term-length (e.g. very long-running log, huge term length growth, or a position overflow caused by corrupted position bookkeeping).","commonSituations":"Extremely long-lived clusters accumulating positions near 2^31/2^32 boundaries with small term lengths, misconfigured term-length, or an internal bug where positions were advanced incorrectly.","solutions":["Increase the log term-length (aeron.term.length) so the position space is larger","Archive and truncate/rollover the log, or start a fresh cluster log from a snapshot","Audit position bookkeeping — reaching max position normally requires pathological conditions","If caused by a leadership/election bug, capture logs and file an issue"],"exampleFix":"// before (default 64KB term buffers on log channel)\nAeron.Context ctx = new Aeron.Context();\n// after\nctx.termBufferLength(1 << 20); // larger term length, bigger position space","handlingStrategy":"validation","validationCode":"if (publication.position() >= publication.maxPossiblePosition()) { /* rollover / enlarge term length */ }","typeGuard":null,"tryCatchPattern":"try { publisher.appendMessage(...); } catch (ClusterException e) { /* rotate log / reconfigure term length */ }","preventionTips":["Use sufficiently large term-length for long-lived clusters","Monitor publication position vs max position","Archive/snapshot and truncate logs periodically"],"tags":["aeron-cluster","publication","position-limit","configuration"],"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"}