aeron-io/aeron · error · ArchiveException

recording events publication at max position, term-length="…

Error message

recording events publication at max position, term-length=" + publication.termBufferLength()

What it means

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.

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.

Example fix

// before
AeronUri.parse("aeron:udp?endpoint=localhost:8010|termLength=64")
// after
AeronUri.parse("aeron:udp?endpoint=localhost:8010|termLength=64k")

Defensive patterns

Strategy: validation

Validate before calling

int termLength = uri.getIntValue("termLength");
if (termLength < 64 * 1024) throw new IllegalArgumentException("use realistic termLength >= 64k");

Try / catch

try { proxy.started(recId, sid, pos, ssnId, ts); }
catch (ArchiveException e) {
    if (e.getMessage().contains("max position")) { recreatePublicationWithLargerTermLength(); }
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/1d9b7673fa6f955b. Report an issue: GitHub.

Appendix: source

Thrown at aeron-archive/src/main/java/io/aeron/archive/RecordingEventsProxy.java:148

            {
                break;
            }

            checkResult(position, publication);
        }
        while (--attempts > 0);
    }

    private static void checkResult(final long position, final Publication publication)
    {
        if (position == Publication.CLOSED)
        {
            throw new ArchiveException("recording events publication is closed");
        }

        if (position == Publication.MAX_POSITION_EXCEEDED)
        {
            throw new ArchiveException(
                "recording events publication at max position, term-length=" + publication.termBufferLength());
        }
    }
}

View on GitHub (pinned to 6d60124e15)