aeron-io/aeron · error · ClusterException

log publication at max position: term-length=

Error message

log publication at max position: term-length=${termBufferLength}

What it means

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.

Solutions

1. Increase the log term-length (aeron.term.length) so the position space is larger
2. Archive and truncate/rollover the log, or start a fresh cluster log from a snapshot
3. Audit position bookkeeping — reaching max position normally requires pathological conditions
4. If caused by a leadership/election bug, capture logs and file an issue

Example fix

// before (default 64KB term buffers on log channel)
Aeron.Context ctx = new Aeron.Context();
// after
ctx.termBufferLength(1 << 20); // larger term length, bigger position space

if (publication.position() >= publication.maxPossiblePosition()) { /* rollover / enlarge term length */ }

try { publisher.appendMessage(...); } catch (ClusterException e) { /* rotate log / reconfigure term length */ }

When it happens

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

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

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

• publication at max position: term-length=
• claim exceeds maxPayloadLength of , length=
• message exceeds maxMessageLength of
• ClusterBackup.Context.catchupEndpoint must be set
• local archive control must be IPC

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

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/LogPublisher.java:330

            }

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

        return false;
    }

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

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

    /**
     * {@inheritDoc}
     */
    @Override
    public String toString()
    {
        return "LogPublisher{" +
            "destinationChannel='" + destinationChannel + '\'' +
            '}';
    }
}

View on GitHub (pinned to 6d60124e15)