microsoft/garnet · error · Exception

MaxInlineValueSize value '{MaxInlineValueSize}' ({sizeInByte

Error message

MaxInlineValueSize value '{MaxInlineValueSize}' ({sizeInBytes} bytes) is greater than half the page size ({pageSize / 2} bytes for PageSize {pageSize} bytes).

What it means

Even when within [0, 0xFFFFFE], MaxInlineValueSize must not exceed half the page size so that at least one record (header + key + value) is guaranteed to fit on a single page. With the default 4 KiB page this caps inline values at 2 KiB; raising the value without also raising --page triggers the error.

Source

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

        /// </summary>
        public int MaxInlineValueSizeBytes(long pageSize)
        {
            const long MinBytes = 0;                    // TODO: LogSettings.MinMaxInlineSize
            const long MaxBytes = 0xFFFFFE;             // TODO: LogSettings.MaxInlineValueSizeLimit (= (1 << kValueLengthBits) - 2)

            if (string.IsNullOrEmpty(MaxInlineValueSize))
                return (int)Math.Min(pageSize / 2, KVSettings.DefaultMaxInlineValueSize);

            if (!TryParseSize(MaxInlineValueSize, out var sizeInBytes))
                throw new Exception($"Unable to parse {nameof(MaxInlineValueSize)} value '{MaxInlineValueSize}'. Expected a memory size string (e.g. '4k', '16m').");

            if (sizeInBytes < MinBytes || sizeInBytes > MaxBytes)
                throw new Exception($"{nameof(MaxInlineValueSize)} value '{MaxInlineValueSize}' ({sizeInBytes} bytes) is outside the allowed range [{MinBytes}, {MaxBytes}] bytes.");

            // This check guarantees at least one record fits on a page, because the minimum page size is 4k, and 2k is larger than
            // the PageHeader plus non-value components of a record (RecordInfo, RecordDataHeader, Key, and possible Optional fields).
            if (sizeInBytes > pageSize / 2)
                throw new Exception($"{nameof(MaxInlineValueSize)} value '{MaxInlineValueSize}' ({sizeInBytes} bytes) is greater than half the page size ({pageSize / 2} bytes for PageSize {pageSize} bytes).");

            return (int)sizeInBytes;
        }

        /// <summary>
        /// Parse <see cref="InitialIORecordSize"/> as a byte count.
        /// Returns <see cref="KVSettings.UseDefaultInitialIORecordSize"/> if the value is null or empty (use default).
        /// </summary>
        /// <returns>The byte value used for <c>KVSettings.InitialIORecordSize</c>, or <see cref="KVSettings.UseDefaultInitialIORecordSize"/> if unset.</returns>
        /// <exception cref="Exception">Thrown when the value cannot be parsed.</exception>
        public int GetInitialIORecordSizeBytes()
        {
            if (string.IsNullOrEmpty(InitialIORecordSize))
                return KVSettings.UseDefaultInitialIORecordSize;

            if (!TryParseSize(InitialIORecordSize, out var sizeInBytes))
                throw new Exception($"Unable to parse {nameof(InitialIORecordSize)} value '{InitialIORecordSize}'. Expected a memory size string (e.g. '4k', '8k').");

View on GitHub (pinned to 951b0fc683)

Solutions

1. Lower --max-inline-value-size to at most half the page size.
2. Or raise the page size proportionally, e.g. --page 16m to allow --max-inline-value-size 8m.
3. Omit the flag to use the safe default of min(pageSize/2, DefaultMaxInlineValueSize).

Example fix

# before (fails: 3m > 4m/2 with default page)
garnet-server --max-inline-value-size 3m

# after: raise the page size to match
garnet-server --page 8m --max-inline-value-size 3m

var pageSize = 1L << options.PageSizeBits();
if (ServerOptions.TryParseSize(options.MaxInlineValueSize, out var v) && v > pageSize / 2) {
    throw new ArgumentOutOfRangeException($"MaxInlineValueSize ({v}) must be <= pageSize/2 ({pageSize / 2})");
}

When it happens

Trigger: Setting --max-inline-value-size larger than pageSize/2, e.g. '3m' with the default ~4m page (3m > 2m). Thrown at GarnetServerOptions.cs:931-932.

Common situations: Increasing inline value size to hold bigger payloads without proportionally increasing the page size; assuming the header-field limit (16MiB) is the only constraint.

Related errors

• MutablePercent must be between 10 and 95
• Store Log Memory size or PageCount must be specified
• Index size {IndexMemorySize} should not be less than index m
• Read Cache Log Memory size or PageCount must be specified
• MaxInlineKeySize value '{MaxInlineKeySize}' ({sizeInBytes} b

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