What causes "invalid errorBufferLength=${errorBufferLength}" in aeron-io/aeron?

Set errorBufferLength to the default 1024 or a modest larger value (e.g. 4096) within the valid range

aeron-io/aeron · error · ConfigurationException

invalid errorBufferLength=

Error message

invalid errorBufferLength=${errorBufferLength}

What it means

errorBufferLength sizes the in-memory error buffer written into the ArchiveMarkFile header. When no pre-built markFile is supplied, conclude() requires ERROR_BUFFER_LENGTH_DEFAULT <= errorBufferLength <= Integer.MAX_VALUE - ArchiveMarkFile.HEADER_LENGTH so the buffer fits in the mark file header; otherwise this ConfigurationException is thrown.

Solutions

Set errorBufferLength to the default 1024 or a modest larger value (e.g. 4096) within the valid range
Compute an upper bound: value must be <= Integer.MAX_VALUE - ArchiveMarkFile.HEADER_LENGTH
Remove the override to use Archive.Configuration.ERROR_BUFFER_LENGTH_DEFAULT

Example fix

// before
ctx.errorBufferLength(Integer.MAX_VALUE); // overflows with header length
// after
ctx.errorBufferLength(1024);

Defensive patterns

Strategy: validation

Validate before calling

int v = ctx.errorBufferLength();
if (v < 1024 || v > Integer.MAX_VALUE - ArchiveMarkFile.HEADER_LENGTH) {
    throw new IllegalArgumentException("errorBufferLength out of range");
}

Prevention

Keep errorBufferLength at the default 1024 unless you need larger error capture
Cap any computed size at Integer.MAX_VALUE - ArchiveMarkFile.HEADER_LENGTH
Do not reuse driver error buffer sizes for the archive mark file

When it happens

Trigger: Setting aeron.archive.mark.file.error.buffer.length (or ctx.errorBufferLength(...)) to a negative value, zero, a value below the default (1024), or a value so large it overflows when the mark-file header length is added.

Common situations: Trying to enlarge the error buffer to capture many errors with an over-large value; typos producing tiny/negative sizes; copying a driver-level error buffer length that exceeds the archive mark-file limit.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

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

            if (null == nanoClock)
            {
                nanoClock = SystemNanoClock.INSTANCE;
            }

            if (null != aeron)
            {
                aeronDirectoryName = aeron.context().aeronDirectoryName();
            }

            concludeArchiveId();

            if (null == markFile)
            {
                if (errorBufferLength < ERROR_BUFFER_LENGTH_DEFAULT ||
                    errorBufferLength > Integer.MAX_VALUE - ArchiveMarkFile.HEADER_LENGTH)
                {
                    throw new ConfigurationException("invalid errorBufferLength=" + errorBufferLength);
                }

                markFile = new ArchiveMarkFile(this);
            }

            MarkFile.ensureMarkFileLink(
                archiveDir,
                new File(markFile.parentDirectory(), ArchiveMarkFile.FILENAME),
                ArchiveMarkFile.LINK_FILENAME);

            errorHandler = CommonContext.setupErrorHandler(
                errorHandler, new DistinctErrorLog(markFile.errorBuffer(), epochClock, US_ASCII));

            final ExpandableArrayBuffer tempBuffer = new ExpandableArrayBuffer();

            final String clientName = "archive archiveId=" + archiveId;
            if (null == aeron)
            {

View on GitHub (pinned to 6d60124e15)