microsoft/FASTER · error · FasterException

Entry does not fit on page

Error message

Entry does not fit on page

What it means

Append was called with a record whose serialized size requires more slots than fit on a single log page. FasterLog never splits a record across pages, so ValidateAllocatedLength (FasterLog.cs:2880) rejects any allocation exceeding the allocator page size.

Solutions

1. Increase FasterLogOptions.PageSize so it exceeds the maximum record size you append.
2. Split large payloads into multiple records or store large blobs externally and append a reference.
3. Validate payload size against page size before Enqueue and reject/split oversize records early.
4. Use the tryAppend pattern (TryEnqueue) to fail gracefully and log oversize payloads.

Example fix

// before
log.Append(bigBuffer); // may exceed page

// after
if (bigBuffer.Length > options.PageSize - Unsafe.SizeOf<FasterLogHeader>())
    throw new ArgumentException("Record larger than log page; use chunking");
log.Append(bigBuffer);

const int HeaderOverhead = 20; // approximate serialized header size
if (payload.Length + HeaderOverhead > options.PageSize)
    throw new ArgumentException($"Record of {payload.Length} bytes exceeds log page size {options.PageSize}");

try { log.Append(payload); } catch (FasterException ex) when (ex.Message == "Entry does not fit on page") { ChunkAndAppend(payload); }

When it happens

Trigger: Enqueue/Append of a byte[]/IMemoryOwner payload whose length (plus record header and alignment) exceeds the log's page size (default 64 MB when unspecified but small when PageSize is configured explicitly).

Common situations: Configuring a small page size for testing and then writing production-sized payloads; appending images/blobs bigger than one page; forgetting that the limit applies to the serialized record, not the logical object.

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

• Byte array provided has invalid length
• Already recovered until address
• Attempting to enqueue into a completed log
• Cannot commit in read-only mode
• Cannot scan disposed log instance

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

Appendix: source

Thrown at cs/src/core/FasterLog/FasterLog.cs:2880

        {
            // commit record has negative length field to differentiate from normal records
            if (logChecksum == LogChecksumType.None)
            {
                *(int*)dest = -length;
                return;
            }
            else if (logChecksum == LogChecksumType.PerEntry)
            {
                *(int*)(dest + 8) = -length;
                *(ulong*)dest = Utility.XorBytes(dest + 8, length + 4);
            }
        }

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        private void ValidateAllocatedLength(int numSlots)
        {
            if (numSlots > allocator.PageSize)
                throw new FasterException("Entry does not fit on page");
        }
    }
}

View on GitHub (pinned to 321d872eab)