microsoft/garnet · error · ArgumentException

filePath is required for disk-backed trees.

Error message

filePath is required for disk-backed trees.

What it means

Thrown by the BfTreeService constructor when StorageBackendType.Disk is selected but no filePath is provided. Disk-backed BfTree instances require a file path to persist data; without one, the native layer cannot initialize the storage backend. The ArgumentException includes the parameter name 'filePath' for diagnostics.

Source

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

        /// <param name="cbSizeByte">Circular buffer size in bytes (hot-data cache for Disk; total capacity for Memory).</param>
        /// <param name="cbMinRecordSize">Minimum record size.</param>
        /// <param name="cbMaxRecordSize">Maximum record size.</param>
        /// <param name="cbMaxKeyLen">Maximum key length.</param>
        /// <param name="leafPageSize">Leaf page size.</param>
        public BfTreeService(
            StorageBackendType storageBackend = StorageBackendType.Disk,
            string filePath = null,
            bool enableSnapshots = false,
            ulong cbSizeByte = 0,
            uint cbMinRecordSize = 0,
            uint cbMaxRecordSize = 0,
            uint cbMaxKeyLen = 0,
            uint leafPageSize = 0)
        {
            _storageBackend = storageBackend;
            _filePath = filePath;
            if (storageBackend == StorageBackendType.Disk && string.IsNullOrEmpty(filePath))
                throw new ArgumentException("filePath is required for disk-backed trees.", nameof(filePath));
            byte[] pathBytes = filePath != null ? Encoding.UTF8.GetBytes(filePath) : null;
            byte useSnapshot = (byte)(enableSnapshots ? 1 : 0);
            fixed (byte* pp = pathBytes)
            {
                _tree = NativeBfTreeMethods.bftree_create(
                    cbSizeByte, cbMinRecordSize, cbMaxRecordSize, cbMaxKeyLen, leafPageSize,
                    (byte)storageBackend, pp, pathBytes?.Length ?? 0,
                    useSnapshot);
            }
            if (_tree == 0)
                throw new InvalidOperationException("Failed to create BfTree instance.");
        }

        /// <summary>
        /// Creates a BfTreeService wrapping an existing native tree pointer (e.g. from snapshot restore).
        /// Takes ownership of the pointer.
        /// </summary>
        internal BfTreeService(nint treePtr, StorageBackendType storageBackend, string filePath = null)

View on GitHub (pinned to 951b0fc683)

Solutions

1. Provide a valid file path when using StorageBackendType.Disk.
2. If you don't need disk persistence, use StorageBackendType.Memory or the appropriate non-disk backend.
3. Validate the filePath parameter before constructing the BfTreeService.

Example fix

// before
var svc = new BfTreeService(
    storageBackend: StorageBackendType.Disk,
    filePath: null  // missing
);

// after
var svc = new BfTreeService(
    storageBackend: StorageBackendType.Disk,
    filePath: "/var/lib/garnet/bftree.dat"
);

if (storageBackend == StorageBackendType.Disk && string.IsNullOrWhiteSpace(filePath))
    throw new ArgumentException("A file path is required when using disk-backed BfTree storage.", nameof(filePath));

static bool IsBfTreeConfigValid(StorageBackendType backend, string filePath) =>
    backend != StorageBackendType.Disk || !string.IsNullOrWhiteSpace(filePath);

When it happens

Trigger: Creating a BfTreeService with storageBackend=StorageBackendType.Disk and filePath=null or empty string. The check is at BfTreeService.cs:160.

Common situations: Programmatically constructing a BfTreeService without specifying a file path when disk storage is intended; config or code path that defaults filePath to null but sets the backend to Disk; forgetting to pass the filePath argument when calling the constructor.

Related errors

• Failed to create BfTree instance.
• bftree_scan_with_count returned a null handle.
• bftree_scan_with_end_key returned a null handle.
• Native handle is null.
• Snapshot path is required.

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