{"record":{"id":"1c8f09e5c4485a7d","repo":"microsoft/FASTER","slug":"entry-does-not-fit-on-page","errorCode":null,"errorMessage":"Entry does not fit on page","messagePattern":"Entry does not fit on page","errorType":"exception","errorClass":"FasterException","httpStatus":null,"severity":"error","filePath":"cs/src/core/Allocator/AllocatorBase.cs","lineNumber":1380,"sourceCode":"            }\n            catch\n            {\n                localTailPageOffset.Offset = PageSize;\n                Interlocked.Exchange(ref TailPageOffset.PageAndOffset, localTailPageOffset.PageAndOffset);\n                throw;\n            }\n        }\n\n        /// <summary>\n        /// Try allocate, no thread spinning allowed\n        /// </summary>\n        /// <param name=\"numSlots\">Number of slots to allocate</param>\n        /// <returns>The allocated logical address, or 0 in case of inability to allocate</returns>\n        [MethodImpl(MethodImplOptions.AggressiveInlining)]\n        public long TryAllocate(int numSlots = 1)\n        {\n            if (numSlots > PageSize)\n                throw new FasterException(\"Entry does not fit on page\");\n\n            PageOffset localTailPageOffset = default;\n            localTailPageOffset.PageAndOffset = TailPageOffset.PageAndOffset;\n\n            // Necessary to check because threads keep retrying and we do not\n            // want to overflow offset more than once per thread\n            if (localTailPageOffset.Offset > PageSize)\n            {\n                if (NeedToWait(localTailPageOffset.Page + 1))\n                    return 0; // RETRY_LATER\n                return -1; // RETRY_NOW\n            }\n\n            // Determine insertion index.\n            localTailPageOffset.PageAndOffset = Interlocked.Add(ref TailPageOffset.PageAndOffset, numSlots);\n\n            int page = localTailPageOffset.Page;\n            int offset = localTailPageOffset.Offset - numSlots;","sourceCodeStart":1362,"sourceCodeEnd":1398,"githubUrl":"https://github.com/microsoft/FASTER/blob/321d872eabda6a0345c8bd76419f89723ed864ae/cs/src/core/Allocator/AllocatorBase.cs#L1362-L1398","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Increase LogSettings.PageSizeBits so a page can hold the largest record.","Store large payloads externally (file/object store) and keep a reference or small key in FASTER.","Reduce the record size (split into multiple entries or use the object allocator for large values)."],"exampleFix":"// before\nvar settings = new LogSettings { LogDevice = ..., PageSizeBits = 12 }; // 4KB pages\nstore.Upsert(key, hugeByteArray); // 1MB value - cannot fit on a page\n\n// after\nvar settings = new LogSettings { LogDevice = ..., PageSizeBits = 22 }; // 4MB pages\n// or store the blob externally and upsert only its reference","handlingStrategy":"validation","validationCode":"int pageSize = 1 << settings.PageSizeBits;\nint maxRecordBytes = /* serialized size of largest key+value */;\nif (maxRecordBytes > pageSize)\n    throw new ArgumentException($\"Record of {maxRecordBytes} bytes exceeds page size {pageSize}; increase PageSizeBits\");","typeGuard":null,"tryCatchPattern":"try { store.Upsert(key, value); session.CompletePending(true); }\ncatch (FasterException ex) when (ex.Message == \"Entry does not fit on page\") { /* raise PageSizeBits or store payload externally */ }","preventionTips":["Size PageSizeBits to comfortably exceed your maximum serialized record size.","Keep large blobs out of the log; store references instead.","Re-validate record sizes after schema/serialization changes."],"tags":["csharp","faster","allocation","record-size"],"backgroundTag":"payload-too-large","analyzedSha":"321d872eabda6a0345c8bd76419f89723ed864ae","analyzedAt":"2026-09-15T22:18:00.693Z","contentChangedAt":"2026-09-15T22:18:00.693Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}