aeron-io/aeron · error · ArchiveException

segment file length not in valid range

Error message

segment file length not in valid range: ${segmentFileLength}

What it means

After the power-of-two check, Archive validates segmentFileLength is within TERM_MIN_LENGTH..TERM_MAX_LENGTH (the term buffer bounds). Archive throws ArchiveException if the configured value falls outside that range.

Solutions

1. Choose a segmentFileLength between TERM_MIN_LENGTH and TERM_MAX_LENGTH (and a power of two), e.g. 1 << 30.
2. If smaller segments are needed, lower the term length constraints in the driver configuration instead.
3. Clamp/validate the value programmatically before configuring Archive.Context.

Example fix

// before
ctx.segmentFileLength(1 << 16); // 64KiB, below TERM_MIN_LENGTH
// after
ctx.segmentFileLength(1 << 30); // 1GiB, valid power-of-2 in range

if (segmentFileLength < Archive.Configuration.TERM_MIN_LENGTH ||
    segmentFileLength > Archive.Configuration.TERM_MAX_LENGTH)
{
    throw new IllegalArgumentException("segmentFileLength out of range: " + segmentFileLength);
}

When it happens

Trigger: Setting Archive.Context.segmentFileLength(...) to a value smaller than the minimum term length or larger than the maximum (e.g. 64KB or 8GB+), then launching the archive.

Common situations: Trying to shrink segments below the Aeron term minimum to save disk, or enlarging beyond the term maximum to reduce segment count.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• segment file length not a power of 2
• 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/8bc3589087bc0bb4. Report an issue: GitHub.

Appendix: source

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

                            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();

            if (null == catalog)
            {
                catalog = new Catalog(

View on GitHub (pinned to 6d60124e15)