microsoft/FASTER · error · Exception

Invalid index size

Error message

Invalid index size

What it means

ServerOptions.IndexSizeCachelines parses the IndexSize option and rounds it down to the previous power of two; if the adjusted hash index size is below 64 bytes or above 2^37 bytes it throws "Invalid index size". The hash index must be a power-of-2-sized table within a supported range because addressing masks the low bits of hashes.

Solutions

1. Set IndexSize to a valid power-of-2 byte size between 64 and 128GB, e.g. "1g" or "268435456".
2. Compute the index size from expected key count (roughly 64B per ~64 entries * overhead) and keep it comfortably above the 64-byte floor.
3. Log/inspect the parsed value of IndexSize before server start to catch unit/parse mistakes.

Example fix

// before
options.IndexSize = "32"; // too small -> throws
// after
options.IndexSize = "1g"; // valid power-of-2 index size

long bytes = ParseSize(options.IndexSize);
if (bytes < 64 || bytes > (1L << 37) || (bytes & (bytes - 1)) != 0)
    throw new ArgumentException($"IndexSize must be a power-of-2 between 64 and 128GB, got {options.IndexSize}");

try { settings = options.GetSettings(); } catch (Exception) { options.IndexSize = "1g"; settings = options.GetSettings(); }

When it happens

Trigger: Setting ServerOptions.IndexSize to a value that parses to < 64 bytes (e.g. "32" or "0") or > 128GB (1L<<37), then building the server settings via GetSettings.

Common situations: Typo'd units (e.g. "64k" interpreted as 64 bytes for a tiny index); misconfigured memory budget strings; copying a log-size value into IndexSize; leaving IndexSize empty or invalid such that ParseSize yields 0.

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

• LogDir specified without enabling tiered storage…
• Insufficient page size to write delta
• Out of order message within session
• Unexpected status of SubscribeKV
• Cannot use BlittableParameterSerializer with non-blittable…

AI-assisted analysis of microsoft/FASTER@321d872eab (2026-09-15). Data as JSON: /api/errors/e2f60b7d8027bf15. Report an issue: GitHub.

Appendix: source

Thrown at cs/remote/src/FASTER.server/Servers/ServerOptions.cs:150

        /// <returns></returns>
        public int SegmentSizeBits()
        {
            long size = ParseSize(SegmentSize);
            long adjustedSize = PreviousPowerOf2(size);
            if (size != adjustedSize)
                logger?.LogInformation($"Warning: using lower disk segment size than specified (power of 2)");
            return (int)Math.Log(adjustedSize, 2);
        }

        /// <summary>
        /// Get index size
        /// </summary>
        /// <returns></returns>
        public int IndexSizeCachelines()
        {
            long size = ParseSize(IndexSize);
            long adjustedSize = PreviousPowerOf2(size);
            if (adjustedSize < 64 || adjustedSize > (1L << 37)) throw new Exception("Invalid index size");
            if (size != adjustedSize)
                logger?.LogInformation($"Warning: using lower hash index size than specified (power of 2)");
            return (int)(adjustedSize / 64);
        }

        /// <summary>
        /// Get log settings
        /// </summary>
        /// <param name="logSettings"></param>
        /// <param name="checkpointSettings"></param>
        /// <param name="indexSize"></param>
        public void GetSettings(out LogSettings logSettings, out CheckpointSettings checkpointSettings, out int indexSize)
        {
            logSettings = new LogSettings { PreallocateLog = false };

            logSettings.PageSizeBits = PageSizeBits();
            logger?.LogInformation($"[Store] Using page size of {PrettySize((long)Math.Pow(2, logSettings.PageSizeBits))}");

View on GitHub (pinned to 321d872eab)