aeron-io/aeron · error · ClusterException

publication is not connected

Error message

publication is not connected

What it means

SnapshotTaker.checkResult inspects the result of Publication.offer/tryClaim when writing a snapshot. A result equal to Publication.NOT_CONNECTED means the snapshot publication has no connected subscribers (no consensus module/image is consuming it), so the snapshot data cannot be delivered. The taker throws a ClusterException instead of silently dropping snapshot content.

Solutions

1. Ensure the consensus module is running and subscribed to the snapshot channel before triggering a snapshot
2. Verify aeron.cluster.snapshot.channel / stream-id configuration matches on both sides
3. Check network connectivity and endpoints between container and consensus module
4. Retry the snapshot after the publication connects (subscriber registered)

// Before triggering a snapshot, confirm the consensus module subscription exists
if (!consensusModuleProxy.isSnapshotChannelConnected()) { waitForSnapshotSubscriber(); }

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

When it happens

Trigger: checkResultAndIdle is called after offer/tryClaim returned Publication.NOT_CONNECTED — the snapshot publication's channel has no active subscriber (e.g. consensus module already closed or channel URI wrong).

Common situations: Taking a snapshot after the consensus module shut down its subscription, misconfigured snapshot channel endpoint in the cluster config, or network partition between cluster members during snapshot transfer.

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=
• ControlSession.RESPONSE_NOT_CONNECTED_MSG + ": " + session
• log publication is closed
• log publication at max position: term-length=

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

Appendix: source

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

    protected static void checkInterruptStatus()
    {
        if (Thread.currentThread().isInterrupted())
        {
            throw new AgentTerminationException("interrupted");
        }
    }

    /**
     * Check the result of offering to a publication when writing a snapshot.
     *
     * @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.

View on GitHub (pinned to 6d60124e15)