aeron-io/aeron · error · ConfigurationException

aeronArchiveContext must be set

Error message

aeronArchiveContext must be set

What it means

A persistent subscription needs an AeronArchive.Context to create its archive client connection for replay requests. conclude() throws ConfigurationException when the aeronArchiveContext field is null, since without it the subscription cannot issue replay/position queries to the archive.

Solutions

  1. Create and attach an AeronArchive.Context: ctx.aeronArchiveContext(new AeronArchive.Context()) before conclude().
  2. Reuse the AeronArchive.Context of an existing AeronArchive client so both share configuration.
  3. Ensure the archive control request/response channels are configured in that context.

Example fix

// before
final PersistentSubscription.Context ctx = new PersistentSubscription.Context()
    .recordingId(1)
    .liveChannel("aeron:udp?endpoint=localhost:10000")
    .liveStreamId(5)
    .replayChannel("aeron:udp?endpoint=localhost:10001")
    .replayStreamId(7);
ctx.conclude(); // throws: aeronArchiveContext must be set

// after
ctx.aeronArchiveContext(new AeronArchive.Context()
    .controlRequestChannel("aeron:udp?endpoint=localhost:8010"));
ctx.conclude();
Defensive patterns

Strategy: validation

Validate before calling

if (null == ctx.aeronArchiveContext()) {
    throw new IllegalArgumentException("aeronArchiveContext must be set before conclude()");
}

Try / catch

try {
    ctx.conclude();
} catch (ConfigurationException e) {
    // attach a default AeronArchive.Context and retry once
}

Prevention

When it happens

Trigger: conclude() invoked without calling context.aeronArchiveContext(AeronArchive.Context) (or a context-supplying constructor).

Common situations: Building the subscription standalone in tests without the archive context; refactoring code that used to inherit an AeronArchive context; DI/config frameworks failing to inject the archive context object.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

Thrown at aeron-archive/src/main/java/io/aeron/archive/client/PersistentSubscription.java:1707

            if (Strings.isEmpty(liveChannel))
            {
                throw new ConfigurationException("liveChannel must be set");
            }

            if (Strings.isEmpty(replayChannel))
            {
                throw new ConfigurationException("replayChannel must be set");
            }

            if (Aeron.NULL_VALUE == replayStreamId)
            {
                throw new ConfigurationException("replayStreamId must be set");
            }

            if (null == aeronArchiveContext)
            {
                throw new ConfigurationException("aeronArchiveContext must be set");
            }

            if (null == listener)
            {
                listener = new NoOpPersistentSubscriptionListener();
            }

            if (0 > recordingId)
            {
                throw new ConfigurationException("invalid recordingId " + recordingId);
            }

            if (FROM_LIVE > startPosition)
            {
                throw new ConfigurationException("invalid startPosition " + startPosition);
            }

            final ChannelUri replayChannelUri = ChannelUri.parse(replayChannel);

View on GitHub (pinned to 6d60124e15)