What causes "snapshot ended unexpectedly: " in aeron-io/aeron?

Check Archive service logs for recording or replay errors at the failure time

aeron-io/aeron · critical · ClusterException

snapshot ended unexpectedly

Error message

snapshot ended unexpectedly: <image>

What it means

While replaying a standby snapshot from the archive, the agent polls fragments and expects the image to deliver data until completion. If polling returns no fragments and the image is closed, the snapshot stream terminated early and ClusterException is thrown because the snapshot is incomplete.

Solutions

Check Archive service logs for recording or replay errors at the failure time
Verify the snapshot recording still exists in the archive catalogue
Inspect network connectivity between the cluster node and the archive
Recovery will use an earlier snapshot; if none is valid, reseed the node from scratch or from a live leader

Example fix

// before: replaying from an archive session that is torn down mid-transfer
// (no retry / integrity check)

// after: validate snapshot availability before joining
if (!archive.listRecording(recordingId, 0, 1))
{
    throw new ClusterException("snapshot recording missing: " + recordingId);
}

Defensive patterns

Strategy: retry

Validate before calling

// verify the snapshot recording is fully available before replay
if (!archive.listRecording(recordingId, 0, 1))
{
    throw new IllegalStateException("snapshot recording missing: " + recordingId);
}

Try / catch

catch (ClusterException e)
{
    if (e.getMessage().startsWith("snapshot ended unexpectedly"))
    {
        log.error("snapshot replay interrupted: {}", e.getMessage());
        // recovery proceeds from an earlier snapshot or the live leader
    }
    throw e;
}

Prevention

Keep the Archive service highly available and monitored
Do not delete snapshot recordings referenced by the recording log
Ensure reliable network to the archive endpoints
Take snapshots frequently so a corrupt one costs little recovery time

When it happens

Trigger: Thrown during snapshot polling when image.poll() returns 0 fragments, archive events were polled, and image.isClosed() is true before the snapshot replay finished.

Common situations: Archive service restarted mid-replay; snapshot recording deleted or expired; network drop to the archive; archive storage failure corrupting or truncating the recording.

Related errors

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

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/ConsensusModuleAgent.java:2814

        {
            final Image image = awaitImage(sessionId, subscription);
            final ConsensusModuleSnapshotAdapter adapter = new ConsensusModuleSnapshotAdapter(image, this);

            idleStrategy.reset();
            while (true)
            {
                final int fragments = adapter.poll();
                if (adapter.isDone())
                {
                    break;
                }

                if (0 == fragments)
                {
                    pollArchiveEvents();
                    if (image.isClosed())
                    {
                        throw new ClusterException("snapshot ended unexpectedly: " + image);
                    }
                }

                idle(fragments);
            }

            for (final PendingServiceMessageTracker tracker : pendingServiceMessageTrackers)
            {
                tracker.verify();
                tracker.reset();
            }

            if (null != consensusModuleExtension)
            {
                consensusModuleExtension.onStart(this, image);
            }
        }

View on GitHub (pinned to 6d60124e15)