microsoft/FASTER · error · FasterException

Path is too long

Error message

Path {filename} is too long

What it means

LocalStorageDevice on Windows opens files with Win32 APIs subject to MAX_PATH limits. Because segment ids append a ".<segment>" suffix to the filename, the constructor reserves 11 characters and rejects any filename longer than Native32.WIN32_MAX_PATH - 11.

Solutions

1. Shorten the base path/filename so the full path (plus segment suffix) stays under the MAX_PATH budget.
2. Move the log/checkpoint directory closer to the drive root (e.g., C:\data\).
3. Enable Windows long-path support (registry LongPathsEnabled + manifest longPathAware) if your build and target framework support it.
4. Use a junction/subst drive to map a long directory chain to a short drive letter.

Example fix

// before
var device = new LocalStorageDevice(@"C:\Users\alice\AppData\Local\MyVeryLongApplicationName\Checkpoints\HybridLog");
// after
var device = new LocalStorageDevice(@"C:\data\faster\hlog"); // short base path; segment suffix still fits under MAX_PATH

const int MaxPath = 260; if (path.Length > MaxPath - 11) throw new ArgumentException($"Path too long: {path.Length} chars; max {MaxPath - 11} to allow segment suffix");

try { device = new LocalStorageDevice(path); } catch (FasterException e) when (e.Message.Contains("too long")) { log.LogError(e, "Log path exceeds MAX_PATH budget"); }

When it happens

Trigger: new LocalStorageDevice(path, ...) where path.Length > Native32.WIN32_MAX_PATH - 11 (i.e., roughly > 249 characters on Windows).

Common situations: Deeply nested checkpoint/log directories in long Windows paths; user-profile-relative paths on corporate machines; building segment filenames with long prefixes.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Error creating log file for
• Error reading from log file
• Error writing to log file
• Error binding log handle for
• Cannot use LocalStorageDevice from non-Windows OS platform…

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

Appendix: source

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

        /// <param name="initialLogFileHandles">Optional set of preloaded safe file handles, which can speed up hydration of preexisting log file handles</param>
        /// <param name="useIoCompletionPort">Whether we use IO completion port with polling</param>
        protected internal LocalStorageDevice(string filename,
                                      bool preallocateFile = false,
                                      bool deleteOnClose = false,
                                      bool disableFileBuffering = true,
                                      long capacity = Devices.CAPACITY_UNSPECIFIED,
                                      bool recoverDevice = false,
                                      IEnumerable<KeyValuePair<int, SafeFileHandle>> initialLogFileHandles = null,
                                      bool useIoCompletionPort = true)
                : base(filename, GetSectorSize(filename), capacity)
        {
            if (!RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
            {
                throw new FasterException("Cannot use LocalStorageDevice from non-Windows OS platform, use ManagedLocalStorageDevice instead.");
            }

            if (filename.Length > Native32.WIN32_MAX_PATH - 11)     // -11 to allow for ".<segment>"
                throw new FasterException($"Path {filename} is too long");

            ThrottleLimit = 120;
            this.useIoCompletionPort = useIoCompletionPort;
            this._disposed = false;

            if (useIoCompletionPort)
            {
                ThreadPool.GetMaxThreads(out int workerThreads, out _);
                ioCompletionPort = Native32.CreateIoCompletionPort(new SafeFileHandle(new IntPtr(-1), false), IntPtr.Zero, UIntPtr.Zero, (uint)(workerThreads + NumCompletionThreads));
                for (int i = 0; i < NumCompletionThreads; i++)
                {
                    var thread = new Thread(() => new LocalStorageDeviceCompletionWorker().Start(ioCompletionPort, _callback))
                    {
                        IsBackground = true
                    };
                    thread.Start();
                }
            }

View on GitHub (pinned to 321d872eab)