aeron-io/aeron · error · ArchiveException

Aeron client must use a RethrowingErrorHandler

Error message

Aeron client must use a RethrowingErrorHandler

What it means

Archive requires that the Aeron client's subscriber error handler is a RethrowingErrorHandler so that subscriber errors surface to the archive instead of being silently logged/defaulted. Archive throws ArchiveException at startup if aeron.context().subscriberErrorHandler() is not a RethrowingErrorHandler.

Solutions

  1. Set .rethrowErrorHandler() (or subscriberErrorHandler(new RethrowingErrorHandler())) on the Aeron.Context used for the archive's client.
  2. If a custom handler is required elsewhere, create a separate Aeron client for Archive with the rethrowing handler.
  3. Check whether a shared error-handler factory is overriding the archive client's context.

Example fix

// before
Aeron aeron = Aeron.connect(new Aeron.Context().errorHandler(myLoggingHandler));
// after
Aeron aeron = Aeron.connect(new Aeron.Context()
    .errorHandler(myLoggingHandler)
    .subscriberErrorHandler(new RethrowingErrorHandler()));
Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

boolean hasRethrowingHandler(Aeron aeron) {
    return aeron.context().subscriberErrorHandler() instanceof RethrowingErrorHandler;
}

Prevention

When it happens

Trigger: Launching Archive with an Aeron client whose Context has a custom subscriberErrorHandler set (or left default) that is not RethrowingErrorHandler.

Common situations: Applications installing a logging ErrorHandler globally, then reusing the same Aeron client for the archive; copying client setup code that sets errorHandler(...) for normal subscriptions.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: source

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

                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)
            {
                countedErrorHandler = new CountedErrorHandler(errorHandler, errorCounter);
            }

            if (null == threadFactory)
            {
                threadFactory = Thread::new;
            }

            if (null == recorderThreadFactory)
            {
                recorderThreadFactory = threadFactory;
            }

View on GitHub (pinned to 6d60124e15)