{"record":{"id":"b0bf9132b9c69a7d","repo":"aeron-io/aeron","slug":"catalogfilesynclevel-catalogfilesynclevel-filesynclevel","errorCode":null,"errorMessage":"catalogFileSyncLevel ${catalogFileSyncLevel} < fileSyncLevel ${fileSyncLevel}","messagePattern":"catalogFileSyncLevel (.+?) < fileSyncLevel (.+?)","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/Archive.java","lineNumber":1204,"sourceCode":"            {\n                throw new RuntimeException(ex);\n            }\n        }\n\n        /**\n         * 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","sourceCodeStart":1186,"sourceCodeEnd":1222,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/Archive.java#L1186-L1222","documentation":"Archive startup validation rejects a configuration where catalogFileSyncLevel is lower than fileSyncLevel. The catalog would then be less durably flushed than the recording files it indexes, weakening crash-recovery guarantees the sync levels are meant to provide. Aeron throws this ConfigurationException during Archive.Context.conclude() before the archive starts.","triggerScenarios":"Setting Archive.Context.fileSyncLevel (or system property aeron.archive.file.sync.level) to a higher value than aeron.archive.catalog.file.sync.level, e.g. fileSyncLevel=2 with catalogFileSyncLevel=0 or 1.","commonSituations":"Operators tune fileSyncLevel for durability (e.g. FORCE for recording files) but leave the catalog property at its weaker default or explicitly set it lower; copying a config file between environments where one has an override; typos swapping the two property values.","solutions":["Set aeron.archive.catalog.file.sync.level >= aeron.archive.file.sync.level (e.g. both 0, 1, or 2)","Lower aeron.archive.file.sync.level to at most the catalog sync level if weaker sync is intentional","If only catalog sync was meant to be configured, remove the fileSyncLevel override so it defaults equal"],"exampleFix":"// before\nArchive.Configuration.FILE_SYNC_LEVEL_PROP_NAME, \"2\"\nArchive.Configuration.CATALOG_FILE_SYNC_LEVEL_PROP_NAME, \"0\"\n// after\nArchive.Configuration.FILE_SYNC_LEVEL_PROP_NAME, \"2\"\nArchive.Configuration.CATALOG_FILE_SYNC_LEVEL_PROP_NAME, \"2\"","handlingStrategy":"validation","validationCode":"if (ctx.catalogFileSyncLevel() < ctx.fileSyncLevel()) {\n    throw new IllegalArgumentException(\"catalogFileSyncLevel must be >= fileSyncLevel\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep both sync levels equal unless you have a measured reason to differ","Document any sync-level overrides in your deployment config","Validate properties in startup scripts before launching the archive"],"tags":["configuration","durability","aeron-archive","sync-level"],"backgroundTag":"conflicting-config-options","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"}