{"record":{"id":"1d9b7673fa6f955b","repo":"aeron-io/aeron","slug":"recording-events-publication-at-max-position-term-length","errorCode":null,"errorMessage":"recording events publication at max position, term-length=\" + publication.termBufferLength()","messagePattern":"recording events publication at max position, term-length=\" \\+ publication\\.termBufferLength\\(\\)","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/RecordingEventsProxy.java","lineNumber":148,"sourceCode":"            {\n                break;\n            }\n\n            checkResult(position, publication);\n        }\n        while (--attempts > 0);\n    }\n\n    private static void checkResult(final long position, final Publication publication)\n    {\n        if (position == Publication.CLOSED)\n        {\n            throw new ArchiveException(\"recording events publication is closed\");\n        }\n\n        if (position == Publication.MAX_POSITION_EXCEEDED)\n        {\n            throw new ArchiveException(\n                \"recording events publication at max position, term-length=\" + publication.termBufferLength());\n        }\n    }\n}\n","sourceCodeStart":130,"sourceCodeEnd":153,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/RecordingEventsProxy.java#L130-L153","documentation":"checkResult also detects Publication.MAX_POSITION_EXCEEDED: the recording events publication reached the maximum representable stream position and can no longer accept offers. The exception includes the publication's term buffer length to aid diagnosis of extreme term-length configurations.","triggerScenarios":"started()/progress()/stopped() offer returns MAX_POSITION_EXCEEDED — the publication has advanced past Long_MAX-aligned position; practically only with tiny term lengths (down to 64 bytes) and very high event volume, or in tests with minimal term buffers.","commonSituations":"Test/CI environments configured with minimal termLength producing quick position overflow; extremely long-lived recording events streams; misconfigured channel with 'termLength' far below the normal 64KB minimums.","solutions":["Increase the channel term-length (e.g. termLength=64k or larger) on the recording events channel.","Restart/recreate the publication; a publication at max position cannot be extended.","Review event emission volume; throttle or aggregate progress events.","If in tests, use realistic term lengths instead of the 64-byte minimum."],"exampleFix":"// before\nAeronUri.parse(\"aeron:udp?endpoint=localhost:8010|termLength=64\")\n// after\nAeronUri.parse(\"aeron:udp?endpoint=localhost:8010|termLength=64k\")","handlingStrategy":"validation","validationCode":"int termLength = uri.getIntValue(\"termLength\");\nif (termLength < 64 * 1024) throw new IllegalArgumentException(\"use realistic termLength >= 64k\");","typeGuard":null,"tryCatchPattern":"try { proxy.started(recId, sid, pos, ssnId, ts); }\ncatch (ArchiveException e) {\n    if (e.getMessage().contains(\"max position\")) { recreatePublicationWithLargerTermLength(); }\n}","preventionTips":["Use default or >= 64k term lengths on recording events channels.","Avoid the 64-byte minimum term length even in tests.","Monitor publication position growth in extremely long-lived streams."],"tags":["publication","max-position","term-length","archive"],"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"}