microsoft/FASTER · error · IOException

Error creating log file for

Error message

Error creating log file for {segmentFileName}, error: {error} 0x({Native32.MakeHRFromErrorCode(error)})

What it means

CreateHandle opens a segment file with CreateFile; if the returned handle is invalid, it builds a message with the Win32 error code and its HRESULT form and throws IOException. A PATH_NOT_FOUND error appends the filename length and MAX_PATH for diagnosis.

Solutions

Create the target directory (Directory.CreateDirectory) before initializing the device.
If the message says 'Path not found', compare name length against MAX_PATH and shorten the path.
Check ACLs / run the process under an account with write access to the segment directory.
Verify the drive/volume is mounted and the path uses valid characters.

Example fix

// before
var device = new LocalStorageDevice(@"D:\faster\hlog\seg-0", ...); // D:\faster\hlog does not exist
// after
Directory.CreateDirectory(@"D:\faster\hlog");
var device = new LocalStorageDevice(@"D:\faster\hlog\seg-0", ...);

Defensive patterns

Strategy: validation

Validate before calling

Directory.CreateDirectory(Path.GetDirectoryName(fullSegmentPath));
if (fullSegmentPath.Length > 260) throw new ArgumentException("Path exceeds MAX_PATH");

Try / catch

try { device.Initialize(...); } catch (IOException e) when (e.Message.Contains("Error creating log file")) { log.LogError(e, "Cannot create segment file; check directory and ACLs"); }

Prevention

Always create the checkpoint/log directory before device initialization.
Run the service under an account with write access to the segment directory.
Verify network drives are mounted before startup.

When it happens

Trigger: Opening/creating a segment file where the directory does not exist (ERROR_PATH_NOT_FOUND), access is denied, path is too long, the disk is unavailable, or the path is malformed.

Common situations: Checkpoint/log directory not created before initializing the device; network drive unavailable; permissions issues under service accounts; path length overflow on Windows.

Understand the failure class

Background: "open() failed", "failed to open file", "cannot create file" — what a file open error means and how to fix it — this error's family across 42 libraries.

Related errors

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

Appendix: source

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

                // FILE_SHARE_DELETE allows multiple FASTER instances to share a single log directory and each can specify deleteOnClose.
                // This will allow the files to persist until all handles across all instances have been closed.
                fileShare |= Native32.FILE_SHARE_DELETE;
            }

            string segmentFileName = GetSegmentFilename(fileName, segmentId, omitSegmentId);
            var logHandle = Native32.CreateFileW(
                segmentFileName,
                fileAccess, fileShare,
                IntPtr.Zero, fileCreation,
                fileFlags, IntPtr.Zero);

            if (logHandle.IsInvalid)
            {
                var error = Marshal.GetLastWin32Error();
                var message = $"Error creating log file for {segmentFileName}, error: {error} 0x({Native32.MakeHRFromErrorCode(error)})";
                if (error == Native32.ERROR_PATH_NOT_FOUND)
                    message += $" (Path not found; name length = {segmentFileName.Length}, MAX_PATH = {Native32.WIN32_MAX_PATH}";
                throw new IOException(message);
            }

            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)
                {

View on GitHub (pinned to 321d872eab)