aeron-io/aeron · error · ArchiveException

archive is not connected

Error message

archive is not connected

What it means

If pollForResponse makes no progress (pollCount == 0) and the control-response subscription is not connected, ReplayMerge throws ArchiveException 'archive is not connected'. This means the client cannot reach the archive control endpoint at all, so pending requests cannot complete.

Solutions

1. Verify the archive is running and listening on the control-request endpoint
2. Check control-request and control-response channel/stream configuration in AeronArchive.Context match the archive's
3. Test network connectivity (firewall, UDP routes) to the archive host
4. Retry once the archive reconnects, or recreate the AeronArchive connection

Example fix

// before
AeronArchive archive = AeronArchive.connect(new AeronArchive.Context().aeron(ctx.aeron())); // default channels
// after: explicit archive endpoints
AeronArchive archive = AeronArchive.connect(new AeronArchive.Context()
    .controlRequestChannel("aeron:udp?endpoint=archivehost:8010")
    .controlResponseChannel("aeron:udp?endpoint=archivehost:0"));

if (!archive.controlResponsePoller().subscription().isConnected()) { waitForArchiveConnection(timeoutMs); }

try { merge.doWork(); }
catch (ArchiveException e) { if (e.getMessage().equals("archive is not connected")) { awaitArchiveAvailability(); retryMerge(); } }

When it happens

Trigger: The control subscription has no active image — archive process down, wrong control channel/stream in AeronArchive.Context, or network partition — while polling for a request response.

Common situations: Firewall or DNS preventing UDP connectivity to the archive control port; archive started later than the client; control-request/control-response channel misconfiguration.

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

• local archive not connected
• failed to fetch remote recording descriptor
• failed to get recording position
• failed to resolve subscription endpoint: channel=" +…
• failed to send bounded replay request

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

Appendix: source

Thrown at aeron-archive/src/main/java/io/aeron/archive/client/ReplayMerge.java:615

        final int pollCount = poller.poll();
        if (poller.isPollComplete())
        {
            if (poller.controlSessionId() == archive.controlSessionId())
            {
                if (poller.code() == ControlResponseCode.ERROR)
                {
                    throw new ArchiveException("archive response for correlationId=" + poller.correlationId() +
                        ", error: " + poller.errorMessage(),
                        (int)poller.relevantId(),
                        poller.correlationId());
                }

                return poller.correlationId() == correlationId;
            }
        }
        else if (pollCount == 0 && !poller.subscription().isConnected())
        {
            throw new ArchiveException("archive is not connected");
        }

        return false;
    }

    private static long polledRelevantId(final AeronArchive archive)
    {
        return archive.controlResponsePoller().relevantId();
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public String toString()
    {
        return "ReplayMerge{" +
            "state=" + state +

View on GitHub (pinned to 6d60124e15)