{"record":{"id":"534ddaa2fe1eeaf8","repo":"aeron-io/aeron","slug":"publication-at-max-position-term-length-publication","errorCode":null,"errorMessage":"publication at max position: term-length=${publication.termBufferLength()}","messagePattern":"publication at max position: term-length=(.+?)","errorType":"console","errorClass":"ClusterException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/service/ConsensusModuleProxy.java","lineNumber":233,"sourceCode":"\n        return false;\n    }\n\n    private static void checkResult(final long position, final Publication publication)\n    {\n        if (Publication.NOT_CONNECTED == position)\n        {\n            throw new ClusterException(\"publication is not connected\");\n        }\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","sourceCodeStart":215,"sourceCodeEnd":237,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/service/ConsensusModuleProxy.java#L215-L237","documentation":"checkResult throws this when a publication operation returns Publication.MAX_POSITION_EXCEEDED. The log publication would exceed the maximum addressable position for its term buffer length (position past 2^31 * term-length territory per term), so the offer is rejected to prevent corrupting position arithmetic.","triggerScenarios":"Offering (offer, tryClaim) through ConsensusModuleProxy when the publication's position reaches MAX_POSITION (roughly Integer.MAX_VALUE * termBufferLength); also reachable via scheduleTimer/cancelTimer/ack/closeSession which share checkResult.","commonSituations":"Very long-running cluster logs with small term-length settings; misconfigured aeron.term.length (e.g. 64KB) on high-throughput clusters; accumulated positions across many terms on an embedded publication.","solutions":["Increase aeron.term.length (e.g. to 1MB/16MB) to raise the maximum position.","Restart/redeploy the cluster so a fresh publication/log is used; archive and replay as needed.","Check for runaway position growth (error loops re-offering endlessly) in the service code.","Verify consistent term-length across all nodes; mismatched configs can cause position anomalies."],"exampleFix":"// before\nAeronCluster.Configuration.termLength(64 * 1024);\n// after\nAeronCluster.Configuration.termLength(1024 * 1024); // or aeron.term.length=1m","handlingStrategy":"validation","validationCode":"long maxPos = (long)Integer.MAX_VALUE * publication.termBufferLength();\nif (publication.position() >= maxPos) {\n    // stop offering; term-length too small for workload\n}","typeGuard":null,"tryCatchPattern":"try {\n    proxy.offer(buffer, offset, length);\n} catch (ClusterException e) {\n    if (e.getMessage().startsWith(\"publication at max position\")) {\n        // reconfigure term-length and restart\n    } else {\n        throw e;\n    }\n}","preventionTips":["Size aeron.term.length for total expected log positions (e.g. 1m+ for high throughput).","Keep term-length identical across all cluster nodes.","Monitor publication position against max in production dashboards."],"tags":["aeron","publication","position","term-length"],"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-16T04:17:20.429Z"}