microsoft/FASTER · error · FasterException

Entry does not fit on page

Error message

Entry does not fit on page

What it means

TryAllocate allocates space in the log's current page; a single record (numSlots) can never be larger than a whole page. If numSlots > PageSize the record physically cannot fit on any page, so the allocator throws eagerly instead of looping forever. This is a hard invariant on record size relative to page configuration.

Solutions

1. Increase LogSettings.PageSizeBits so a page can hold the largest record.
2. Store large payloads externally (file/object store) and keep a reference or small key in FASTER.
3. Reduce the record size (split into multiple entries or use the object allocator for large values).

Example fix

// before
var settings = new LogSettings { LogDevice = ..., PageSizeBits = 12 }; // 4KB pages
store.Upsert(key, hugeByteArray); // 1MB value - cannot fit on a page

// after
var settings = new LogSettings { LogDevice = ..., PageSizeBits = 22 }; // 4MB pages
// or store the blob externally and upsert only its reference

int pageSize = 1 << settings.PageSizeBits;
int maxRecordBytes = /* serialized size of largest key+value */;
if (maxRecordBytes > pageSize)
    throw new ArgumentException($"Record of {maxRecordBytes} bytes exceeds page size {pageSize}; increase PageSizeBits");

try { store.Upsert(key, value); session.CompletePending(true); }
catch (FasterException ex) when (ex.Message == "Entry does not fit on page") { /* raise PageSizeBits or store payload externally */ }

When it happens

Trigger: Upserting a value whose serialized size exceeds PageSize (1 << PageSizeBits), or calling TryAllocate directly with numSlots larger than the page; also extremely long keys/values or oversized byte[] payloads stored inline.

Common situations: Storing large blobs/arrays as values in a blittable store with default PageSizeBits=25 or smaller test page sizes; serializing records that grow after schema changes past the configured page size.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Related errors

• Out of order message within session
• Unexpected status of SubscribeKV
• Cannot use BlittableParameterSerializer with non-blittable…
• The inner list is full!
• The list is empty!

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

Appendix: source

Thrown at cs/src/core/Allocator/AllocatorBase.cs:1380

            }
            catch
            {
                localTailPageOffset.Offset = PageSize;
                Interlocked.Exchange(ref TailPageOffset.PageAndOffset, localTailPageOffset.PageAndOffset);
                throw;
            }
        }

        /// <summary>
        /// Try allocate, no thread spinning allowed
        /// </summary>
        /// <param name="numSlots">Number of slots to allocate</param>
        /// <returns>The allocated logical address, or 0 in case of inability to allocate</returns>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public long TryAllocate(int numSlots = 1)
        {
            if (numSlots > PageSize)
                throw new FasterException("Entry does not fit on page");

            PageOffset localTailPageOffset = default;
            localTailPageOffset.PageAndOffset = TailPageOffset.PageAndOffset;

            // Necessary to check because threads keep retrying and we do not
            // want to overflow offset more than once per thread
            if (localTailPageOffset.Offset > PageSize)
            {
                if (NeedToWait(localTailPageOffset.Page + 1))
                    return 0; // RETRY_LATER
                return -1; // RETRY_NOW
            }

            // Determine insertion index.
            localTailPageOffset.PageAndOffset = Interlocked.Add(ref TailPageOffset.PageAndOffset, numSlots);

            int page = localTailPageOffset.Page;
            int offset = localTailPageOffset.Offset - numSlots;

View on GitHub (pinned to 321d872eab)