aeron-io/aeron · error · ClusterException

publication is not connected

Error message

publication is not connected

What it means

ConsensusModuleProxy.send/checkResult inspects the return code of Publication.offer/tryClaim/scheduleTimer etc. When the result equals Publication.NOT_CONNECTED, meaning no subscribers are currently attached to the consensus module's log/control publication, it throws this ClusterException. It signals that messages cannot currently be delivered to the consensus module.

Solutions

1. Ensure the consensus module is running and connected before invoking the proxy.
2. Retry the operation after a short delay; NOT_CONNECTED is often transient during startup/shutdown.
3. Verify cluster node startup order and that the service is not left over from a previous failed run.
4. Check archive/recording log consistency if the consensus module repeatedly fails to start.

Example fix

// before
proxy.scheduleTimer(correlationId, deadlineMs);
// after
if (!proxy.scheduleTimer(correlationId, deadlineMs)) {
    // publication not connected/closed; retry on next cycle
}

try {
    proxy.scheduleTimer(correlationId, deadlineMs);
} catch (ClusterException e) {
    if (e.getMessage().contains("not connected")) {
        // retry after backoff; consensus module not yet attached
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling ConsensusModuleProxy.scheduleTimer, cancelTimer, offer, tryClaim, ack, or closeSession when the underlying publication has no connected subscriber (consensus module not up, crashed, or publication not yet connected).

Common situations: ClusteredService calling scheduleTimer during startup before the consensus module subscribes; consensus module restarted while a stale service-side proxy publication remains; service started before the cluster node's consensus module agent.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• publication is closed
• publication at max position: term-length=
• publication is closed
• padding exceeds maxFramedLength of , length=
• invalid block length , remaining space in term is

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

Appendix: source

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

                .wrapAndApplyHeader(bufferClaim.buffer(), bufferClaim.offset(), messageHeaderEncoder)
                .correlationId(correlationId)
                .extended(BooleanType.TRUE);

            bufferClaim.commit();

            return true;
        }

        checkResult(position, publication);

        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)