aeron-io/aeron · error · ArchiveException

found existing archive for archiveId=

Error message

found existing archive for archiveId=${archiveId}

What it means

While allocating the archive error counter, the archive found an existing Aeron counter with ARCHIVE_ERROR_COUNT_TYPE_ID already registered for the same archiveId. This means another Archive instance is already running with that identity against the same media driver, so startup fails with an ArchiveException to prevent two archives sharing one identity.

Solutions

  1. Shut down the existing Archive process (or close its Aeron client) before restarting
  2. Use a unique archiveId per Archive instance instead of a hardcoded one
  3. Restart/recreate the media driver so stale counters are cleared if the previous owner is definitively dead
  4. Check via ArchiveCounters.find / aeron counters whether an archive is already registered before starting

Example fix

// before
ctx.archiveId(42); // hardcoded, collides with running archive
// after
ctx.archiveId(System.nanoTime()); // or omit to let it be generated
// and ensure the previous archive is fully closed first
Defensive patterns

Strategy: try-catch

Validate before calling

CountersReader counters = aeron.countersReader();
if (NULL_VALUE != ArchiveCounters.find(counters, ArchiveCounters.ARCHIVE_ERROR_COUNT_TYPE_ID, archiveId)) {
    throw new IllegalStateException("archive already running for archiveId=" + archiveId);
}

Try / catch

try {
    archive.start();
} catch (ArchiveException e) {
    if (e.getMessage().contains("found existing archive")) {
        // stop the other instance or choose a different archiveId, then retry
    }
}

Prevention

When it happens

Trigger: Starting a second Archive process/context with the same archiveId while the first still holds its error counter on the driver; a crashed archive whose counters were not released (driver still up) followed by a restart reusing the archiveId; incorrectly reusing a fixed archiveId across multiple archive instances.

Common situations: Failover scripts restarting the archive while the old process is still connected; misconfigured clusters pointing several archive nodes at one driver with identical archiveId; leftover embedded archives in the same JVM (Aeron client not closed).

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

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

Appendix: source

Thrown at aeron-archive/src/main/java/io/aeron/archive/Archive.java:1359

                aeron = Aeron.connect(
                    new Aeron.Context()
                        .aeronDirectoryName(aeronDirectoryName)
                        .epochClock(epochClock)
                        .nanoClock(nanoClock)
                        .errorHandler(errorHandler)
                        .driverAgentInvoker(mediaDriverAgentInvoker)
                        .useConductorAgentInvoker(true)
                        .subscriberErrorHandler(RethrowingErrorHandler.INSTANCE)
                        .awaitingIdleStrategy(YieldingIdleStrategy.INSTANCE)
                        .clientLock(NoOpLock.INSTANCE)
                        .clientName(clientName));

                if (null == errorCounter)
                {
                    if (NULL_VALUE !=
                        ArchiveCounters.find(aeron.countersReader(), ARCHIVE_ERROR_COUNT_TYPE_ID, archiveId))
                    {
                        throw new ArchiveException("found existing archive for archiveId=" + archiveId);
                    }
                    errorCounter = ArchiveCounters.allocateErrorCounter(aeron, tempBuffer, archiveId);
                }
            }
            else if (!aeron.context().useConductorAgentInvoker())
            {
                throw new ArchiveException(
                    "Aeron client instance must set Aeron.Context.useConductorInvoker(true)");
            }

            if (!(aeron.context().subscriberErrorHandler() instanceof RethrowingErrorHandler))
            {
                throw new ArchiveException("Aeron client must use a RethrowingErrorHandler");
            }

            Objects.requireNonNull(errorCounter, "Error counter must be supplied if aeron client is");

            if (null == countedErrorHandler)

View on GitHub (pinned to 6d60124e15)