How to Fix Git "Filename too long" Error on Windows

The annoying "Filename too long" wall

I ran into a classic Windows headache today while trying to clone a React project with a deeply nested directory structure. Everything started fine, but halfway through the checkout process, Git threw a fit and stopped dead. This isn't a bug in Git itself, but rather a legacy limitation of the Windows API that still haunts us in modern development.

What actually happened

The error message looked exactly like this:

error: unable to create file path/to/very/deeply/nested/directory/structure/that/never/seems/to/end/filename.js: Filename too long
fatal: unable to checkout working tree
warning: clone succeeded, but checkout failed.

Even though the clone "succeeded," the working directory was empty because Git couldn't actually write the files to the disk. On Windows, the default maximum path length (known as MAX_PATH) is 260 characters. This includes the drive letter, colon, backslash, and the terminating null character. If you're working in a folder like C:\Users\Username\Documents\Projects\Company-Internal-Tools\..., you've already burned 60+ characters before even reaching the project root.

The Debug Process

Before jumping into fixes, I checked two things:

Path length: I used a quick PowerShell command to see how long the failing path actually was. It was around 275 characters.
Git version: I made sure I was running a recent version of Git for Windows (git --version), as older versions handled this poorly.

Solution 1: The Git-specific fix (Quickest)

The fastest way to resolve this for Git operations is to tell Git to ignore the MAX_PATH limitation and use the internal UNC (Universal Naming Convention) prefix (\\?\) to handle paths up to 32,767 characters.

Run this command in your terminal (Command Prompt or PowerShell) with administrative privileges:

git config --global core.longpaths true

Why this works: This setting tells Git to use wide-character versions of Windows APIs, which allows it to bypass the 260-character limit. If you don't want to apply this globally, you can run it without --global inside a specific repository, though you usually can't even get into the repo folder if the checkout failed.

After running this, I had to reset the repo to get the files back:

git checkout -f HEAD

Solution 2: Enabling Long Paths in Windows (The permanent fix)

Sometimes fixing Git isn't enough because other tools (like VS Code, Node.js, or File Explorer) might still choke on those long paths. You can enable long path support system-wide in Windows 10 (version 1607 and later) or Windows 11.

Method A: Using the Registry Editor

Press Win + R, type regedit, and hit Enter.
Navigate to: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem
Find the value named LongPathsEnabled.
Right-click it, select Modify, and change the Value data from 0 to 1.
Restart your computer (or at least restart your shell/terminal).

Method B: Using Group Policy (Windows Pro/Enterprise)

Press Win + R, type gpedit.msc, and hit Enter.
Go to: Local Computer Policy > Computer Configuration > Administrative Templates > System > Filesystem.
Find Enable Win32 long paths and set it to Enabled.

Solution 3: The "Surgical" Workaround

If you are on a restricted machine where you can't edit the Registry or run Git as admin, the "low-tech" solution is to shorten your base path. Instead of cloning to your deeply nested Documents folder, clone directly to a folder at the root of your drive.

# Instead of this:
# C:\Users\MyUser\Work\Archives\2024\Projects\MyRepo

# Do this:
C:\> mkdir dev
C:\> cd dev
C:\dev> git clone https://github.com/org/very-long-repo-name.git

By moving the project root from 60 characters deep to 7 characters deep (C:\dev\), you gain 53 characters of "breathing room" for your nested node_modules or package structures.

Verification steps

To confirm the fix worked, I performed the following:

Check Git Config: Run git config core.longpaths. It should return true.
Retry Checkout: Run git checkout [branch-name]. If it finishes without the "Filename too long" error, you're good.
File Access: Try to open one of the deeply nested files in your code editor. If you can edit and save it, the OS-level long path support is functioning.

Lessons Learned

Windows is the outlier: Linux and macOS rarely face this issue because their path limits are much higher by default (usually 4096 characters).
Project Structure: Even though we can fix this, it's generally a good practice to avoid excessively deep nesting. In the JavaScript ecosystem, node_modules is the primary offender, but modern package managers like pnpm use symlinks which can exacerbate the path length issue on Windows.
CI/CD: If you have Windows-based build runners (like GitHub Actions Windows runners), make sure to include the git config core.longpaths true step in your initialization scripts to prevent pipeline failures.