microsoft/garnet · error · Exception

InitialIORecordSize value '{InitialIORecordSize}' ({sizeInBy

Error message

InitialIORecordSize value '{InitialIORecordSize}' ({sizeInBytes} bytes) exceeds the page size ({1L << PageSizeBits()} bytes).

What it means

InitialIORecordSize is the size of a single read issued when loading a record from disk, so it must not exceed the page size (1 << PageSizeBits). A value larger than a page is nonsensical because a record cannot span more than a page boundary here; GetInitialIORecordSizeBytes() rejects it.

Source

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

        /// <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').");

            if (sizeInBytes <= 0)
                throw new Exception($"{nameof(InitialIORecordSize)} value '{InitialIORecordSize}' ({sizeInBytes} bytes) must be positive.");

            if (sizeInBytes > 1L << PageSizeBits())
                throw new Exception($"{nameof(InitialIORecordSize)} value '{InitialIORecordSize}' ({sizeInBytes} bytes) exceeds the page size ({1L << PageSizeBits()} bytes).");

            return (int)sizeInBytes;
        }

        /// <summary>
        /// Get AOF settings
        /// </summary>
        /// <param name="dbId">DB ID</param>
        /// <param name="tsavoriteLogSettings">Tsavorite log settings</param>
        public void GetAofSettings(int dbId, out TsavoriteLogSettings[] tsavoriteLogSettings)
        {
            // Validate sizes up-front (invariant across sublogs) so we don't allocate devices
            // or commit managers that would need to be disposed if validation fails.
            var memorySizeBits = AofMemorySizeBits();
            var pageSizeBits = AofPageSizeBits();
            var segmentSizeBits = AofSegmentSizeBits();

            // Tsavorite requires MemorySize >= 2 * PageSize (so at least two pages fit in memory).

View on GitHub (pinned to 951b0fc683)

Solutions

1. Keep --initial-io-record-size <= the page size (default page is ~4 KiB).
2. Or raise --page to be >= the desired IO record size.
3. Omit the flag to use the built-in default, which is already within bounds.

Example fix

# before (fails: 8k > 4k page)
garnet-server --initial-io-record-size 8k

# after: align with a larger page
garnet-server --page 16k --initial-io-record-size 8k

var pageSize = 1L << options.PageSizeBits();
if (!string.IsNullOrEmpty(options.InitialIORecordSize)
    && ServerOptions.TryParseSize(options.InitialIORecordSize, out var io)
    && io > pageSize) {
    throw new ArgumentOutOfRangeException($"InitialIORecordSize ({io}) must be <= pageSize ({pageSize})");
}

When it happens

Trigger: Setting --initial-io-record-size larger than the page size, e.g. '8k' with --page 4k. Thrown at GarnetServerOptions.cs:954-955.

Common situations: Raising the IO read size without checking the configured page size; mismatched values copied across configs.

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/9f7a6e1511b8d024. Report an issue: GitHub.