aeron-io/aeron · error · IllegalArgumentException

Invalid errorBufferLength

Error message

Invalid errorBufferLength: <errorBufferLength>

What it means

ClusterMarkFile's constructor validates that the configured error buffer length is between ERROR_BUFFER_MIN_LENGTH and ERROR_BUFFER_MAX_LENGTH inclusive, throwing IllegalArgumentException otherwise. The error buffer in the mark file has a fixed header layout and a bounded allowed size, so out-of-range values cannot be honored.

Solutions

1. Set errorBufferLength to a value within the allowed range (use the library's ERROR_BUFFER_MIN_LENGTH/MAX_LENGTH constants; the default 1MB-style value in ClusterMarkFile is safe).
2. Check the cluster context property (e.g. clusteredServiceErrorBufferLength) in your configuration for a wrong unit or zero.
3. Align the value with any existing mark file so an existing header's errorBufferLength is reused consistently.

Example fix

// before
ctx.errorBufferLength(0);
// after
ctx.errorBufferLength(ERROR_BUFFER_MIN_LENGTH); // e.g. 1024, or the library default

// java
if (errorBufferLength < ClusterMarkFile.ERROR_BUFFER_MIN_LENGTH ||
    errorBufferLength > ClusterMarkFile.ERROR_BUFFER_MAX_LENGTH) {
    throw new IllegalArgumentException("errorBufferLength out of range: " + errorBufferLength);
}
clusteredContext.errorBufferLength(errorBufferLength);

try {
    ClusterMarkFile markFile = new ClusterMarkFile(file, ...errorBufferLength...);
} catch (IllegalArgumentException e) {
    // correct the configured value and retry once with the default
}

When it happens

Trigger: Constructing a ClusterMarkFile (directly or via cluster/service configuration) with an errorBufferLength below the minimum or above the maximum, e.g. passing 0, a negative value, or an excessively large buffer.

Common situations: Typo in cluster context configuration (e.g. setting bytes to KB), a config file supplying 0, or copying a constant from the wrong unit.

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

• name + " cannot be negative: value=" + value
• gapLength must be smaller than gapRadix
• media type is mandatory
• unsupported time unit
• ClusterMarkFile headerLength=

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

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/service/ClusterMarkFile.java:138

     * @param file              full qualified file to the {@link MarkFile}.
     * @param type              of cluster component the {@link MarkFile} represents.
     * @param errorBufferLength for storing the error log.
     * @param epochClock        for checking liveness against.
     * @param timeoutMs         for the activity check on an existing {@link MarkFile}.
     * @param filePageSize      for aligning file length to.
     * @since 1.48.0
     */
    public ClusterMarkFile(
        final File file,
        final ClusterComponentType type,
        final int errorBufferLength,
        final EpochClock epochClock,
        final long timeoutMs,
        final int filePageSize)
    {
        if (errorBufferLength < ERROR_BUFFER_MIN_LENGTH || errorBufferLength > ERROR_BUFFER_MAX_LENGTH)
        {
            throw new IllegalArgumentException("Invalid errorBufferLength: " + errorBufferLength);
        }

        LogBufferDescriptor.checkPageSize(filePageSize);

        final boolean markFileExists = file.exists();
        final int totalFileLength =
            BitUtil.align(HEADER_LENGTH + errorBufferLength, filePageSize);

        final MessageHeaderDecoder messageHeaderDecoder = new MessageHeaderDecoder();

        final long candidateTermId;
        if (markFileExists)
        {
            final int currentHeaderOffset = headerOffset(file);
            final MarkFile existingMarkFile = new MarkFile(
                file,
                true,
                currentHeaderOffset + MarkFileHeaderDecoder.versionEncodingOffset(),

View on GitHub (pinned to 6d60124e15)