microsoft/garnet · error · Exception

{propName} '{value}' (effective {adjustedSize} bytes after r

Error message

{propName} '{value}' (effective {adjustedSize} bytes after rounding to previous power of 2) must be at least {MinPageSizeBytes} bytes to ensure a worst-case record fits within a single page.

What it means

Garnet enforces a minimum page size of 512 bytes (MinPageSizeBytes) to ensure a worst-case record fits within a single page. ValidatedPageSizeBits() rounds the configured size down to the nearest power of two and rejects anything below 512. This applies to main log page size, object store page size, and any configuration that delegates to ValidatedPageSizeBits().

Source

Thrown at libs/server/Servers/ServerOptions.cs:164

        /// Minimum main-log / read-cache page size in bytes. A worst-case inline record at default Garnet settings
        /// (MaxInlineKeySize = 128B Tsavorite default, single-byte namespace, all optional fields, max length-byte
        /// encoding, max filler) plus the 64-byte page header is ~490 bytes when the value-overflow threshold is
        /// at its largest allowed value relative to PageSize (effective value &lt; effective page); 512 bytes is the
        /// smallest power-of-2 page size that accommodates this and prevents Tsavorite's "Entry does not fit on page".
        /// </summary>
        public const long MinPageSizeBytes = 512L;

        /// <summary>
        /// Validate and convert a page-size configuration value to bits, enforcing <see cref="MinPageSizeBytes"/>.
        /// </summary>
        protected int ValidatedPageSizeBits(string value, string propName)
        {
            var size = ParseSize(value, out _);
            var adjustedSize = PreviousPowerOf2(size);
            if (size != adjustedSize)
                logger?.LogInformation("Warning: using lower {PropName} than specified (power of 2)", propName);
            if (adjustedSize < MinPageSizeBytes)
                throw new Exception($"{propName} '{value}' (effective {adjustedSize} bytes after rounding to previous power of 2) must be at least {MinPageSizeBytes} bytes to ensure a worst-case record fits within a single page.");
            return (int)Math.Log(adjustedSize, 2);
        }

        /// <summary>
        /// Get page size
        /// </summary>
        /// <returns></returns>
        public int PageSizeBits() => ValidatedPageSizeBits(PageSize, nameof(PageSize));

        /// <summary>
        /// Get pub/sub page size
        /// </summary>
        /// <returns></returns>
        public long PubSubPageSizeBytes()
        {
            long size = ParseSize(PubSubPageSize, out _);
            long adjustedSize = PreviousPowerOf2(size);
            if (size != adjustedSize)

View on GitHub (pinned to 951b0fc683)

Solutions

Set the page size to at least 512 bytes (e.g., --page 512 or higher, or use suffixes like --page 1k).
Remove the page size override entirely to use Garnet's default (typically 32m).
If specifying a value between 256 and 511, round up to 512 explicitly.

Example fix

// before
--page 256

// after
--page 512

Defensive patterns

Strategy: validation

Validate before calling

const long MinPage = 512;
var size = ServerOptions.ParseSize(options.PageSize, out _);
var rounded = PreviousPowerOf2(size);
if (rounded < MinPage)
    throw new InvalidOperationException($"Page size {options.PageSize} rounds to {rounded} bytes, minimum is {MinPage}.");

Prevention

Never set page size below 512 bytes.
Use human-readable suffixes (--page 32m) to avoid unit confusion.
Validate all page-size configs in a startup health check script.

When it happens

Trigger: Calling ValidatedPageSizeBits() (via PageSizeBits(), ObjPageSizeBits(), etc.) with a value that rounds down below 512 bytes. For example, --page 256 or --page 500 (rounds to 256).

Common situations: Setting --page to a very small value to reduce memory; misconfiguring size units (e.g., writing --page 1 thinking it means 1KB instead of 1 byte); using a config template with an old or incorrect page size.

Related errors

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