aeron-io/aeron · error · ClusterException

max position exceeded: term-length=

Error message

max position exceeded: term-length=

What it means

sendKeepAlive polls the ingress publication's position after offering a keep-alive message. When the offer returns Publication.MAX_POSITION_EXCEEDED, the publication has advanced past the maximum addressable position for its term buffers, so no further messages can be sent. The library throws ClusterException to surface that the ingress publication is unusable and must be re-established.

Solutions

1. Close the AeronCluster client and reconnect (connect()), which creates a fresh ingress publication with a new position range.
2. Check cluster health — the cluster is not draining ingress if positions grow unchecked; investigate slow session/consumer handling.
3. Reduce ingress send rate or batch size to keep the publication position below the max.
4. Catch ClusterException in the keep-alive loop and treat it as a signal to re-establish the cluster session.

Example fix

// before
cluster.sendKeepAlive(); // throws ClusterException at max position
// after
try { cluster.sendKeepAlive(); } catch (ClusterException e) { cluster.close(); cluster = AeronCluster.connect(ctx); }

if (cluster.ingressPublication().position() >= Publication.MAX_POSITION_EXCEEDED) { reconnectCluster(); }

try { cluster.sendKeepAlive(); } catch (ClusterException e) { if (e.getMessage().startsWith("max position exceeded")) { reconnectCluster(); } else { throw e; } }

When it happens

Trigger: Calling AeronCluster.sendKeepAlive() repeatedly on a long-lived client whose ingress publication position exceeds Long 2^46-ish max position — i.e. offering messages faster than the cluster consumes them over very long sessions, or a stuck cluster letting the position run past the limit.

Common situations: Long-running cluster clients (days/weeks) sending high-volume ingress without reconnecting; a paused/overloaded cluster failing to drain publications; keep-alive itself offered after the publication hit the limit.

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 is closed
• publication at max position: term-length=
• ingress publication is closed
• failed to add new leader ingress publication…
• publication is not connected

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

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/client/AeronCluster.java:514

            final long position = publication.tryClaim(length, bufferClaim);

            trackIngressPublicationResult(position);

            if (position > 0)
            {
                sessionKeepAliveEncoder
                    .wrapAndApplyHeader(bufferClaim.buffer(), bufferClaim.offset(), messageHeaderEncoder)
                    .leadershipTermId(leadershipTermId)
                    .clusterSessionId(clusterSessionId);

                bufferClaim.commit();

                return true;
            }

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

            if (--attempts <= 0)
            {
                break;
            }

            idleStrategy.idle();
        }

        return false;
    }

    /**
     * Sends an admin request to initiate a snapshot action in the cluster. This request requires elevated privileges.
     *
     * @param correlationId for the request.
     * @return {@code true} if the request was sent or {@code false} otherwise.

View on GitHub (pinned to 6d60124e15)