aeron-io/aeron · error · ConfigurationException

AeronArchive.Context.messageRetryAttempts must be > 0, got:

Error message

AeronArchive.Context.messageRetryAttempts must be > 0, got:

What it means

Context.conclude() validates that messageRetryAttempts, the number of retries for control protocol requests/responses, is strictly positive. A value of 0 or negative means the retry mechanism would be disabled or infinite/degenerate, so ConfigurationException reports the offending value.

Solutions

Set a positive value, e.g. ctx.messageRetryAttempts(3), before connect().
Fix the properties file/system property so io.aeron.archive.client.message.retry.attempts parses to a positive integer.
Validate the parsed number at config-load time and fall back to AeronArchive.Configuration.MESSAGE_RETRY_ATTEMPTS_DEFAULT on bad input.
Log the configured value before connect() to catch bad parsing early.

Example fix

// before
ctx.messageRetryAttempts(Integer.parseInt(props.getProperty("archive.retry", "0")));
// after
int retries = Integer.parseInt(props.getProperty("archive.retry", "3"));
ctx.messageRetryAttempts(Math.max(1, retries));

Defensive patterns

Strategy: validation

Validate before calling

int r = ctx.messageRetryAttempts(); if (r <= 0) { ctx.messageRetryAttempts(AeronArchive.Configuration.MESSAGE_RETRY_ATTEMPTS_DEFAULT); }

Prevention

Clamp parsed retry values with Math.max(1, value) at config load time.
Never encode 'disable' as 0; retries are mandatory in the protocol client.
Unit-test config parsing so bad values surface before connect().
Log the effective messageRetryAttempts value at startup.

When it happens

Trigger: Calling context.messageRetryAttempts(0) or a negative value (e.g. from a misparsed property io.aeron.archive.client.message.retry.attempts) before connect().

Common situations: Properties file containing messageRetryAttempts=0; parsing config strings with Integer.parseInt producing -1 on error; code copying a 'disable retries' flag into the attempts setter.

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/b548996b3ecbef76. Report an issue: GitHub.

Appendix: source

Thrown at aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java:3111

            if (null == controlRequestChannel)
            {
                throw new ConfigurationException("AeronArchive.Context.controlRequestChannel must be set");
            }

            if (null == controlResponseChannel)
            {
                throw new ConfigurationException("AeronArchive.Context.controlResponseChannel must be set");
            }

            if (clientName.length() > Aeron.Configuration.MAX_CLIENT_NAME_LENGTH)
            {
                throw new ConfigurationException(
                    "AeronArchive.Context.clientName length must be <= " + Aeron.Configuration.MAX_CLIENT_NAME_LENGTH);
            }

            if (messageRetryAttempts <= 0)
            {
                throw new ConfigurationException("AeronArchive.Context.messageRetryAttempts must be > 0, got: " +
                    messageRetryAttempts);
            }

            if (null == aeron)
            {
                aeron = Aeron.connect(
                    new Aeron.Context()
                        .aeronDirectoryName(aeronDirectoryName)
                        .clientName(clientName.isEmpty() ? "archive-client" : clientName)
                        .errorHandler(errorHandler)
                        .subscriberErrorHandler(RethrowingErrorHandler.INSTANCE));
                ownsAeronClient = true;
            }

            final ChannelUri requestChannel = applyDefaultParams(controlRequestChannel);
            final ChannelUri responseChannel = applyDefaultParams(controlResponseChannel);
            if (!CONTROL_MODE_RESPONSE.equals(responseChannel.get(MDC_CONTROL_MODE_PARAM_NAME)))
            {

View on GitHub (pinned to 6d60124e15)