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

Set fileIoMaxLength to a power of two >= 64KB, e.g. 1MB (1048576) or 4MB (4194304)

aeron-io/aeron · error · ConfigurationException

invalid fileIoMaxLength=

Error message

invalid fileIoMaxLength=${fileIoMaxLength}

What it means

fileIoMaxLength controls the maximum length of a single file I/O operation in the archive. It must be at least TERM_MIN_LENGTH and a power of two, because the archive maps and slices term buffers in power-of-two chunks. Archive.conclude() throws this ConfigurationException when either constraint is violated.

Solutions

Set fileIoMaxLength to a power of two >= 64KB, e.g. 1MB (1048576) or 4MB (4194304)
Use Archive.Configuration.FILE_IO_MAX_LENGTH_DEFAULT or remove the override entirely
If you need small I/O chunks, use the smallest power of two that satisfies TERM_MIN_LENGTH

Example fix

// before
ctx.fileIoMaxLength(3 * 1024 * 1024) // not a power of two
// after
ctx.fileIoMaxLength(4 * 1024 * 1024) // power of two

Defensive patterns

Strategy: validation

Validate before calling

int v = ctx.fileIoMaxLength();
if (v < 64 * 1024 || Integer.bitCount(v) != 1) {
    throw new IllegalArgumentException("fileIoMaxLength must be a power of two >= 65536");
}

Prevention

Express file I/O sizes as shift expressions (e.g. 1 << 20) so they stay powers of two
Check Integer.bitCount(v) == 1 for power-of-two assertions in config loading
Prefer the default value unless profiling shows a need to change it

When it happens

Trigger: Setting Archive.Configuration.FILE_IO_MAX_LENGTH_PARAM_NAME / aeron.archive.file.io.max.length to a non-power-of-two value (e.g. 3MB) or a value below io.aeron.logbuffer.TermBufferLength TERM_MIN_LENGTH (64KB).

Common situations: Hand-tuning I/O limits for very large or very small recording workloads; using suffixes/multipliers that produce non-power-of-two byte values; copying a default from another system with different minimums.

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

Appendix: source

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

         * Conclude the configuration parameters by resolving dependencies and null values to use defaults.
         */
        @SuppressWarnings("MethodLength")
        public void conclude()
        {
            if ((boolean)IS_CONCLUDED_VH.getAndSet(this, true))
            {
                throw new ConcurrentConcludeException();
            }

            if (catalogFileSyncLevel < fileSyncLevel)
            {
                throw new ConfigurationException(
                    "catalogFileSyncLevel " + catalogFileSyncLevel + " < fileSyncLevel " + fileSyncLevel);
            }

            if (fileIoMaxLength < TERM_MIN_LENGTH || !BitUtil.isPowerOfTwo(fileIoMaxLength))
            {
                throw new ConfigurationException("invalid fileIoMaxLength=" + fileIoMaxLength);
            }

            io.aeron.driver.Configuration.validateMtuLength(controlMtuLength);
            checkTermLength(controlTermBufferLength);

            if (controlChannelEnabled)
            {
                if (null == controlChannel)
                {
                    throw new ConfigurationException("Archive.Context.controlChannel must be set");
                }

                if (!controlChannel.startsWith(CommonContext.UDP_CHANNEL))
                {
                    throw new ConfigurationException(
                        "Archive.Context.controlChannel must be UDP media: uri=" + controlChannel);
                }
            }

View on GitHub (pinned to 6d60124e15)