microsoft/FASTER · error · FasterException

Error binding log handle for

Error message

Error binding log handle for {segmentFileName}: {e}

What it means

After creating a segment file handle, LocalStorageDevice binds it to the thread pool for overlapped-I/O completion callbacks. If ThreadPool.BindHandle throws (e.g., handle already bound, invalid, or disposed), the exception is wrapped in a FasterException with the segment filename for context.

Solutions

1. Construct the device with useIoCompletionPort: false to skip the I/O completion port path.
2. Re-run the operation to rule out a transient handle race during segment creation.
3. Check for duplicate construction/disposal races on the same device instance.
4. Report the inner exception details; verify .NET runtime version health on the host.

Example fix

// before
var device = new LocalStorageDevice(path, deleteOnClose: false);
// after
var device = new LocalStorageDevice(path, deleteOnClose: false, useIoCompletionPort: false);

try { device = new LocalStorageDevice(path, useIoCompletionPort: true); } catch (FasterException e) when (e.Message.StartsWith("Error binding log handle")) { device = new LocalStorageDevice(path, useIoCompletionPort: false); }

When it happens

Trigger: CreateHandle with useIoCompletionPort=true when the newly created SafeFileHandle cannot be bound to the thread pool — typically due to an invalid or already-bound handle or runtime I/O-completion infrastructure failure.

Common situations: Running under constrained environments (some containers/hosting sandboxing) where I/O completion ports behave unexpectedly; handle races during rapid segment create/dispose; corrupted runtime state.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Path is too long
• Error reading from log file
• Error writing to log file
• Error creating log file for
• Failed to schedule work:

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

Appendix: source

Thrown at cs/src/core/Device/LocalStorageDevice.cs:452

            }

            if (preallocateFile && segmentSize != -1)
                SetFileSize(fileName, logHandle, segmentSize);

            if (ioCompletionPort != IntPtr.Zero)
            {
                ThreadPool.GetMaxThreads(out int workerThreads, out _);
                Native32.CreateIoCompletionPort(logHandle, ioCompletionPort, (UIntPtr)(long)logHandle.DangerousGetHandle(), (uint)(workerThreads + NumCompletionThreads));
            }
            else
            {
                try
                {
                    ThreadPool.BindHandle(logHandle);
                }
                catch (Exception e)
                {
                    throw new FasterException("Error binding log handle for " + segmentFileName + ": " + e.ToString());
                }
            }
            return logHandle;
        }

        /// <summary>
        ///
        /// </summary>
        /// <param name="segmentId"></param>
        /// <returns></returns>
        protected string GetSegmentName(int segmentId) => GetSegmentFilename(FileName, segmentId);

        /// <summary>
        /// 
        /// </summary>
        /// <param name="_segmentId"></param>
        /// <returns></returns>
        // Can be used to pre-load handles, e.g., after a checkpoint

View on GitHub (pinned to 321d872eab)