{"record":{"id":"7f75e3fe490bba03","repo":"aeron-io/aeron","slug":"invalid-fileiomaxlength-fileiomaxlength","errorCode":null,"errorMessage":"invalid fileIoMaxLength=${fileIoMaxLength}","messagePattern":"invalid fileIoMaxLength=(.+?)","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/Archive.java","lineNumber":1210,"sourceCode":"         * Conclude the configuration parameters by resolving dependencies and null values to use defaults.\n         */\n        @SuppressWarnings(\"MethodLength\")\n        public void conclude()\n        {\n            if ((boolean)IS_CONCLUDED_VH.getAndSet(this, true))\n            {\n                throw new ConcurrentConcludeException();\n            }\n\n            if (catalogFileSyncLevel < fileSyncLevel)\n            {\n                throw new ConfigurationException(\n                    \"catalogFileSyncLevel \" + catalogFileSyncLevel + \" < fileSyncLevel \" + fileSyncLevel);\n            }\n\n            if (fileIoMaxLength < TERM_MIN_LENGTH || !BitUtil.isPowerOfTwo(fileIoMaxLength))\n            {\n                throw new ConfigurationException(\"invalid fileIoMaxLength=\" + fileIoMaxLength);\n            }\n\n            io.aeron.driver.Configuration.validateMtuLength(controlMtuLength);\n            checkTermLength(controlTermBufferLength);\n\n            if (controlChannelEnabled)\n            {\n                if (null == controlChannel)\n                {\n                    throw new ConfigurationException(\"Archive.Context.controlChannel must be set\");\n                }\n\n                if (!controlChannel.startsWith(CommonContext.UDP_CHANNEL))\n                {\n                    throw new ConfigurationException(\n                        \"Archive.Context.controlChannel must be UDP media: uri=\" + controlChannel);\n                }\n            }","sourceCodeStart":1192,"sourceCodeEnd":1228,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/Archive.java#L1192-L1228","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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"],"exampleFix":"// before\nctx.fileIoMaxLength(3 * 1024 * 1024) // not a power of two\n// after\nctx.fileIoMaxLength(4 * 1024 * 1024) // power of two","handlingStrategy":"validation","validationCode":"int v = ctx.fileIoMaxLength();\nif (v < 64 * 1024 || Integer.bitCount(v) != 1) {\n    throw new IllegalArgumentException(\"fileIoMaxLength must be a power of two >= 65536\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["configuration","aeron-archive","power-of-two","validation"],"backgroundTag":"invalid-config-value","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}