microsoft/garnet · error · InvalidOperationException

bftree_scan_with_count returned a null handle.

Error message

bftree_scan_with_count returned a null handle.

What it means

Thrown by BfTreeService.ScanWithCountByPtrCallback when the native bftree_scan_with_count function returns a null handle (IntPtr.Zero). A null scan handle means the native layer could not begin the scan — typically because the tree pointer is invalid, the tree is in a corrupted state, or an internal native error occurred during scan initialization. The method pins the startKey and passes it to native code.

Source

Thrown at libs/native/bftree-garnet/BfTreeService.cs:307

        {
            return (BfTreeDeleteResult)NativeBfTreeMethods.bftree_delete(treePtr, key.ToPointer(), key.Length);
        }

        /// <summary>
        /// Scan with count via native pointer using a zero-allocation callback.
        /// </summary>
        /// <returns>Number of records passed to the callback.</returns>
        public static int ScanWithCountByPtrCallback(nint treePtr, ReadOnlySpan<byte> startKey, int count, ScanReturnField returnField, ScanRecordAction onRecord)
        {
            nint handle;
            fixed (byte* skp = startKey)
            {
                handle = NativeBfTreeMethods.bftree_scan_with_count(
                    treePtr, skp, startKey.Length, count, (byte)returnField);
            }

            if (handle == nint.Zero)
                throw new InvalidOperationException("bftree_scan_with_count returned a null handle.");

            try
            {
                Span<byte> buffer = stackalloc byte[8192];
                return DrainScanIteratorWithCallback(handle, buffer, returnField, onRecord);
            }
            finally
            {
                NativeBfTreeMethods.bftree_scan_drop(handle);
            }
        }

        /// <summary>
        /// Scan with end key via native pointer using a zero-allocation callback.
        /// </summary>
        /// <returns>Number of records passed to the callback.</returns>
        public static int ScanWithEndKeyByPtrCallback(nint treePtr, ReadOnlySpan<byte> startKey, ReadOnlySpan<byte> endKey, ScanReturnField returnField, ScanRecordAction onRecord)
        {

View on GitHub (pinned to 951b0fc683)

Solutions

1. Verify the treePtr is valid and the owning BfTreeService has not been disposed.
2. Ensure scans are not initiated after the tree is closed or during disposal.
3. Check native error logs or stderr for the specific reason the scan handle was null.
4. Guard against calling scan methods on freed/invalid pointers by tracking BfTreeService lifecycle.

Example fix

// before: using a disposed tree's pointer
using (var svc = new BfTreeService(...))
{
    var ptr = svc.TreePointer;
} // svc disposed here
BfTreeService.ScanWithCountByPtrCallback(ptr, ...); // invalid ptr

// after: scan within the service lifetime
using (var svc = new BfTreeService(...))
{
    var ptr = svc.TreePointer;
    BfTreeService.ScanWithCountByPtrCallback(ptr, ...); // valid
}

if (treePtr == nint.Zero)
    throw new InvalidOperationException("Cannot scan: tree pointer is null/zero.");
// Verify the owning BfTreeService is still alive before calling scan

static bool IsValidTreePointer(nint treePtr, BfTreeService owner) =>
    treePtr != nint.Zero && !owner.IsDisposed;

try
{
    BfTreeService.ScanWithCountByPtrCallback(treePtr, startKey, count, returnField, onRecord);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("bftree_scan_with_count returned a null handle"))
{
    logger.LogError(ex, "BfTree scan failed — tree pointer may be invalid or disposed.");
    throw;
}

When it happens

Trigger: Calling ScanWithCountByPtrCallback with an invalid or freed treePtr, or when the native tree is in a state that prevents scan initialization. The native bftree_scan_with_count returns 0, which is checked at BfTreeService.cs:306.

Common situations: Using a tree pointer from a BfTreeService that has been disposed; passing a raw pointer that was never valid; concurrent disposal of the tree while a scan is being initiated; native memory corruption.

Related errors

• bftree_scan_with_end_key returned a null handle.
• filePath is required for disk-backed trees.
• Failed to create BfTree instance.
• Native handle is null.
• Snapshot path is required.

AI-assisted analysis of microsoft/garnet@951b0fc683 (2026-08-13). Data as JSON: /api/errors/71ed6e87ad50f8f6. Report an issue: GitHub.