aeron-io/aeron · error · ClusterException

publication at max position: term-length=

Error message

publication at max position: term-length=${publication.termBufferLength()}

What it means

checkResult received Publication.MAX_POSITION_EXCEEDED from offer/tryClaim, meaning the snapshot publication reached the terminal position of its term buffer arithmetic (64-bit position space for the term-length configuration). Snapshot publishing cannot continue safely at that position, so the taker throws with the configured term buffer length for diagnosis.

Solutions

  1. Close and recreate the publication (start a new snapshot/publication at a fresh position)
  2. Increase the term-length/term-buffer-length configuration to extend the position range
  3. Audit for position bookkeeping bugs that advance the publication position incorrectly

Example fix

// before
defaultTermBufferLength(64 * 1024)
// after
defaultTermBufferLength(1024 * 1024)
Defensive patterns

Strategy: try-catch

Validate before calling

// Recreate publications well before position exhaustion
if (publication.position() > Long.MAX_VALUE - margin) { recreatePublication(); }

Try / catch

try { snapshotTaker.snapshot(...); } catch (ClusterException e) { startNewSnapshotWithFreshPublication(); }

Prevention

When it happens

Trigger: checkResultAndIdle is called after offer/tryClaim returned Publication.MAX_POSITION_EXCEEDED — the publication advanced beyond the maximum representable position for its term-length configuration.

Common situations: Extremely long-lived publications with tiny term buffers and unbounded data, snapshot publications reused far beyond intended volume, or position bookkeeping corruption.

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/1d09385ce6480922. Report an issue: GitHub.

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/service/SnapshotTaker.java:196

     *
     * @param position    of an offer or try claim to a publication.
     * @param publication on which the offer or try claim was attempted.
     */
    protected static void checkResult(final long position, final Publication publication)
    {
        if (Publication.NOT_CONNECTED == position)
        {
            throw new ClusterException("publication is not connected");
        }

        if (Publication.CLOSED == position)
        {
            throw new ClusterException("publication is closed");
        }

        if (Publication.MAX_POSITION_EXCEEDED == position)
        {
            throw new ClusterException("publication at max position: term-length=" + publication.termBufferLength());
        }
    }

    /**
     * Check the result of offering to a publication when writing a snapshot and then idle after invoking the client
     * agent if necessary.
     *
     * @param position of an offer or try claim to a publication.
     */
    protected void checkResultAndIdle(final long position)
    {
        checkResult(position, publication);
        checkInterruptStatus();
        invokeAgentClient();
        idleStrategy.idle();
    }

    /**

View on GitHub (pinned to 6d60124e15)