aeron-io/aeron · error · ArchiveException

segment file length not a power of 2

Error message

segment file length not a power of 2: ${segmentFileLength}

What it means

Archive validates that the configured segment file length is a power of two because recordings are segmented by masking addresses with (segmentFileLength - 1). Archive throws ArchiveException during context configuration if segmentFileLength is not a power of 2.

Solutions

1. Set segmentFileLength to a power of two within TERM_MIN_LENGTH..TERM_MAX_LENGTH (e.g. 1GB = 1 << 30).
2. Round the desired value up to the next power of two before configuring.
3. Validate user-supplied sizes with BitUtil.isPowerOfTwo before calling segmentFileLength.

Example fix

// before
ctx.segmentFileLength(500 * 1024 * 1024); // not a power of 2
// after
ctx.segmentFileLength(1 << 29); // 512MiB, power of 2

if (!BitUtil.isPowerOfTwo(segmentFileLength))
{
    throw new IllegalArgumentException("segmentFileLength must be a power of 2: " + segmentFileLength);
}

When it happens

Trigger: Setting Archive.Context.segmentFileLength(...) to a non-power-of-2 value such as 100MB (104857600) or 3GB, then launching the archive.

Common situations: Administrators sizing segments in decimal units (e.g. 500MB) instead of binary powers; programmatic config derived from user input without validation.

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

• segment file length not in valid range
• AeronArchive.Context.messageRetryAttempts must be > 0, got:
• Aeron client instance must set…
• Aeron client must use a RethrowingErrorHandler
• Unable to derive…

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

Appendix: source

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

                            aeron,
                            tempBuffer,
                            AeronCounters.ARCHIVE_MAX_CYCLE_TIME_TYPE_ID,
                            "archive-replayer max cycle time in ns: " + threadingMode.name(),
                            archiveId),
                        ArchiveCounters.allocate(
                            aeron,
                            tempBuffer,
                            AeronCounters.ARCHIVE_CYCLE_TIME_THRESHOLD_EXCEEDED_TYPE_ID,
                            "archive-replayer work cycle time exceeded count: threshold=" +
                                SystemUtil.formatDuration(replayerCycleThresholdNs) + " " + threadingMode.name(),
                            archiveId),
                        replayerCycleThresholdNs);
                }
            }

            if (!isPowerOfTwo(segmentFileLength))
            {
                throw new ArchiveException("segment file length not a power of 2: " + segmentFileLength);
            }
            else if (segmentFileLength < TERM_MIN_LENGTH || segmentFileLength > TERM_MAX_LENGTH)
            {
                throw new ArchiveException("segment file length not in valid range: " + segmentFileLength);
            }

            if (null == authenticatorSupplier)
            {
                authenticatorSupplier = Configuration.authenticatorSupplier();
            }

            if (null == authorisationServiceSupplier)
            {
                authorisationServiceSupplier = Configuration.authorisationServiceSupplier();
            }

            concludeRecordChecksum();
            concludeReplayChecksum();

View on GitHub (pinned to 6d60124e15)