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

Solutions

1. Increase aeron.term.length (e.g. to 1MB/16MB) to raise the maximum position.
2. Restart/redeploy the cluster so a fresh publication/log is used; archive and replay as needed.
3. Check for runaway position growth (error loops re-offering endlessly) in the service code.
4. Verify consistent term-length across all nodes; mismatched configs can cause position anomalies.

Example fix

// before
AeronCluster.Configuration.termLength(64 * 1024);
// after
AeronCluster.Configuration.termLength(1024 * 1024); // or aeron.term.length=1m

long maxPos = (long)Integer.MAX_VALUE * publication.termBufferLength();
if (publication.position() >= maxPos) {
    // stop offering; term-length too small for workload
}

try {
    proxy.offer(buffer, offset, length);
} catch (ClusterException e) {
    if (e.getMessage().startsWith("publication at max position")) {
        // reconfigure term-length and restart
    } else {
        throw e;
    }
}

When it happens

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

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

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

• recording events publication at max position, term-length="…
• padding exceeds maxFramedLength of , length=
• invalid block length , remaining space in term is
• improperly formatted block:
• assumed term length does not match metadata: termLength=

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

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/service/ConsensusModuleProxy.java:233

        return false;
    }

    private 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());
        }
    }
}

View on GitHub (pinned to 6d60124e15)