aeron-io/aeron · error · ConfigurationException

catalogFileSyncLevel

Error message

catalogFileSyncLevel ${catalogFileSyncLevel} < fileSyncLevel ${fileSyncLevel}

What it means

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.

Solutions

1. Set aeron.archive.catalog.file.sync.level >= aeron.archive.file.sync.level (e.g. both 0, 1, or 2)
2. Lower aeron.archive.file.sync.level to at most the catalog sync level if weaker sync is intentional
3. If only catalog sync was meant to be configured, remove the fileSyncLevel override so it defaults equal

Example fix

// before
Archive.Configuration.FILE_SYNC_LEVEL_PROP_NAME, "2"
Archive.Configuration.CATALOG_FILE_SYNC_LEVEL_PROP_NAME, "0"
// after
Archive.Configuration.FILE_SYNC_LEVEL_PROP_NAME, "2"
Archive.Configuration.CATALOG_FILE_SYNC_LEVEL_PROP_NAME, "2"

if (ctx.catalogFileSyncLevel() < ctx.fileSyncLevel()) {
    throw new IllegalArgumentException("catalogFileSyncLevel must be >= fileSyncLevel");
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• invalid fileIoMaxLength=
• Archive.Context.controlChannel must be set
• Archive.Context.controlChannel must be UDP media: uri=
• local control channel must be IPC media: uri=
• Archive.Context.replicationChannel must be set

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

Appendix: source

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

            {
                throw new RuntimeException(ex);
            }
        }

        /**
         * 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");
                }

View on GitHub (pinned to 6d60124e15)