microsoft/garnet · critical · Exception

AofPageSize (effective {effectivePage} after rounding down t

Error message

AofPageSize (effective {effectivePage} after rounding down to a power of two) cannot be larger than AofSegmentSize (effective {effectiveSegment}). Increase --aof-segment-size to at least {effectivePage}, or reduce --aof-page-size.

What it means

Garnet validates that the AOF page size does not exceed the AOF segment size. The page is the in-memory unit and the segment is the on-disk unit; a page larger than a segment is structurally invalid in Tsavorite's log. The check uses log2 bits: pageSizeBits > segmentSizeBits triggers the error.

Source

Thrown at libs/server/Servers/GarnetServerOptions.cs:998

                var effectiveMemory = PrettySize(1L << memorySizeBits);
                var effectivePage = PrettySize(1L << pageSizeBits);
                var minMemory = PrettySize(1L << (pageSizeBits + 1));
                var msg = $"AofMemorySize (effective {effectiveMemory} after rounding down to a power of two) " +
                          $"must be at least twice AofPageSize (effective {effectivePage}). " +
                          $"Increase --aof-memory to at least {minMemory}, or reduce --aof-page-size.";
                logger?.LogError("{msg}", msg);
                throw new Exception(msg);
            }

            if (pageSizeBits > segmentSizeBits)
            {
                var effectivePage = PrettySize(1L << pageSizeBits);
                var effectiveSegment = PrettySize(1L << segmentSizeBits);
                var msg = $"AofPageSize (effective {effectivePage} after rounding down to a power of two) " +
                          $"cannot be larger than AofSegmentSize (effective {effectiveSegment}). " +
                          $"Increase --aof-segment-size to at least {effectivePage}, or reduce --aof-page-size.";
                logger?.LogError("{msg}", msg);
                throw new Exception(msg);
            }

            // AofPageSize must be at least twice the main-log PageSize. An AOF entry mirrors a single
            // main-log write (key + value/input + small overhead); raw-string SETs can be as large as
            // the main-log PageSize (values above MaxInlineValueSize overflow to the heap on the main
            // store but are still written in full to the AOF), and object commands like LPUSH/HSET can
            // push the AOF entry even higher. Throw a clear error here so users do not hit the runtime
            // "Entry does not fit on page" path with a stalled session.
            var mainPageSizeBits = PageSizeBits();
            if (pageSizeBits < mainPageSizeBits + 1)
            {
                var effectiveAofPage = PrettySize(1L << pageSizeBits);
                var effectiveMainPage = PrettySize(1L << mainPageSizeBits);
                var minAofPage = PrettySize(1L << (mainPageSizeBits + 1));
                var msg = $"AofPageSize (effective {effectiveAofPage} after rounding down to a power of two) " +
                          $"must be at least twice the main-log PageSize (effective {effectiveMainPage}). " +
                          $"Increase --aof-page-size to at least {minAofPage} (and --aof-memory to at least {PrettySize(1L << (mainPageSizeBits + 2))}), " +
                          $"or reduce --page.";

View on GitHub (pinned to 951b0fc683)

Solutions

Increase --aof-segment-size to at least the effective --aof-page-size value.
Reduce --aof-page-size so it does not exceed the segment size.
Remove both overrides to use Garnet defaults where segment is always larger than page.

Example fix

// before
--aof-page-size 1g --aof-segment-size 512m

// after
--aof-page-size 256m --aof-segment-size 1g

Defensive patterns

Strategy: validation

Validate before calling

var pageBits = options.AofPageSizeBits();
var segBits = options.AofSegmentSizeBits();
if (pageBits > segBits)
    throw new InvalidOperationException($"AOF page ({1L << pageBits} bytes) exceeds segment ({1L << segBits} bytes).");

Try / catch

try { options.GetAofSettings(dbId, out var settings); }
catch (Exception ex) when (ex.Message.Contains("AofPageSize") && ex.Message.Contains("AofSegmentSize"))
{ logger.LogError("AOF page/segment mismatch: {Msg}", ex.Message); throw; }

Prevention

Maintain the size hierarchy: page < memory and page <= segment.
Document the size ordering convention in your deployment config.
Validate the entire AOF size chain in a pre-startup health check.

When it happens

Trigger: Calling GetAofSettings() when AofPageSizeBits() > AofSegmentSizeBits(). Occurs when --aof-page-size (after rounding) is larger than --aof-segment-size. For example, --aof-page-size 1g --aof-segment-size 512m.

Common situations: Raising --aof-page-size for large writes without also raising --aof-segment-size; copying a config with mismatched AOF size tiers; using very small segment sizes on memory-constrained devices.

Related errors

AI-assisted analysis of microsoft/garnet@951b0fc683 (2026-08-13). Data as JSON: /api/errors/8260c8e5d32e20f0. Report an issue: GitHub.