Git on Windows: Filename too long and the core.longpaths fix
Windows still caps many paths at 260 characters. Shorten the clone root, enable core.longpaths system-wide, and turn on the OS long path setting.

Introduction & Quick Summary
error: unable to index file 'apps/web/src/...': Filename too long on Windows is not a Git bug and not a corrupt repository. Windows still enforces a 260-character limit for many path operations, the checkout path is built from your clone directory plus every directory in the repository, and Git for Windows ships with long-path support switched off. The same repository clones fine on macOS or Linux, which is why the error is often reported as "it only fails on my machine".
What actually resolves it, from least to most invasive:
- Move the clone.
C:\src\repoinstead ofC:\Users\you\Documents\Projects\2026\reporemoves dozens of characters before Git starts. - Enable
core.longpaths.git config --system core.longpaths truefrom an elevated prompt is the standard fix for Git for Windows. - Enable the OS setting if you want other tools to agree: the
LongPathsEnabledregistry value plus a manifest on the application. - Avoid the path entirely with sparse checkout or a deeper project layout when the offending files belong to a dependency you do not need to check out.
| Message | Where it appears | Meaning |
|---|---|---|
unable to index file ... Filename too long | git add | The path exceeds the limit while staging |
unable to checkout working tree | git clone, git checkout | Checkout hit the limit partway |
error: invalid path | git checkout | Reserved names or characters on Windows |
Filename too long from npm/node | Post-checkout install | The tool, not Git, hit a path limit |
Core Mechanics, Signatures & Reproducible Setup
Windows has two different limits. The classic MAX_PATH is 260 characters for the full path (drive, directories, file name). NTFS itself allows 32,767 characters, and starting with Windows 10 version 1607 the Win32 API can use the longer limit when the process opts in through a manifest and the machine has LongPathsEnabled set. Git for Windows uses plain Win32 calls, so it needs both its own core.longpaths switch and, in some commands, the OS opt-in.
Git builds the path as <worktree root>\<relative path>, so the root matters as much as the repository. A relative path of 180 characters inside a repository cloned to a 75-character root already exceeds 260. Reproduce the limit with a deliberately deep tree:
mkdir deep && cd deep && git init
p="a/$(printf 'b%.0s/%.0s' {1..40})c/$(printf 'd%.0s/%.0s' {1..40})leaf.txt"
mkdir -p "$(dirname "$p")" && echo x > "$p"
git add -A && git commit -m "deep tree"Clone that repository into a long directory on Windows and the checkout stops with unable to checkout working tree, leaving the index populated and the working tree incomplete:
git clone https://example.com/deep.git C:\Users\me\Documents\Projects\team\service\checkoutThe fix is one config value in the right file:
# elevated prompt: applies to every user and every repository
git config --system core.longpaths true
git config --global --get core.longpaths # confirm: true--system matters because git.exe reads the system config first; a --global value works only when the OS long-path setting is also enabled. With the OS setting off, Git can still fail at 260 even with core.longpaths=true, because the underlying file API refuses.
Key Comparison Table
The limit belongs to the OS and the tool, not to the repository, so the same tree behaves differently on each platform.
| Platform / tool | Path limit | Notes |
|---|---|---|
| Windows without opt-in | 260 characters | Applies to most Win32 file calls |
Windows with LongPathsEnabled | ~32,000 | Requires manifest plus registry |
| Git for Windows, default | 260 | core.longpaths is false |
Git for Windows, core.longpaths=true | ~32,000 | Still needs the OS opt-in in some cases |
| Linux ext4 | 4,096 bytes total, 255 per component | Long paths work; exhaust PATH_MAX rarely |
| macOS APFS | 1,024 bytes per component | Case-insensitive by default |
There are four practical ways to get the files on disk, in increasing order of disruption:
| Approach | Effort | Works when |
|---|---|---|
| Shorten the clone root | One command | The excess is under ~50 characters |
core.longpaths=true | One config, may need admin | Git is the only tool that complains |
| Sparse checkout | Per-repository setup | Only a few deep directories are needed |
| Restructure the repository | Changes history | Paths are genuinely too deep for every client |
Practical Edge Cases, Error Fixes & Deep Dive Code Examples
Find the offenders before changing anything
Do not guess which path is too long. Ask Git for the longest ones, then compare with the clone root length:
git ls-tree -r --name-only HEAD | awk '{ print length, $0 }' | sort -rn | head -10187 apps/web/node_modules/.pnpm/@scope+pkg@1.2.3/node_modules/@scope/pkg/dist/esm/internal/helpers/index.js
176 packages/ui/src/components/forms/inputs/advanced/date-range-picker/stories/basic.stories.tsxIf the top entry is 40 characters longer than the 260 minus your root, moving the clone is cheaper than any Git setting. If it is 200 characters longer, the repository layout itself is the problem.
Enable the OS long-path setting
The registry value makes the Win32 API accept long paths for applications that declare support. Set it from an elevated PowerShell, then reboot for existing processes to pick it up:
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
-Name LongPathsEnabled -Value 1 -PropertyType DWORD -Forcegit config --system core.longpaths true
git --versiongit --version must be run in a new shell, otherwise the old environment keeps the previous config. Some Git distributions include a manifest that declares long-path support; others do not, which is the reason core.longpaths=true alone sometimes changes nothing.
Sparse checkout for one deep dependency
When the deep paths belong to a workspace you do not need, a partial clone plus sparse checkout avoids materialising them at all:
git clone --no-checkout --filter=blob:none https://example.com/monorepo.git
cd monorepo
git sparse-checkout init --cone
git sparse-checkout set apps/api packages/shared
git checkout mainThis is also the right answer on CI runners with slow filesystems, since it skips the blobs you never read.
Cleaning up after a failed checkout
A failed checkout leaves the index and the working tree in disagreement, and the next git status reports deleted files that were never written. Reset deliberately; git checkout . will try to write the same long paths again and fail identically.
git reset --hard HEAD
git status --short | headIf the failure happened during git clone, the repository directory may be missing the .git files it needs for a retry. Delete the directory and clone again with the corrected settings rather than trying to repair it in place.
Case sensitivity, reserved names, and invalid path
Windows rejects names that other platforms allow: a trailing dot or space, CON, PRN, AUX, NUL, COM1, LPT1, and a colon anywhere but the drive letter. Git reports these as invalid path rather than "too long", and core.protectNTFS is what makes Git refuse them on checkout to avoid creating something Windows cannot open.
git config --global core.protectNTFS false # avoids the failure, but creates confusing namesPrefer fixing the tree: git mv aux.txt aux-file.txt and commit the rename, so every platform gets a path that works. Disabling the protection is a local workaround that other Windows users will hit again.
Common Compilation/Runtime Mistakes & Version Gotchas
Setting core.longpaths per repository. It only affects that clone. Use --system on the machine that fails, so every repository benefits, including the ones CI clones later.
Expecting the setting to affect other tools. npm, node, python and antivirus scanners enforce their own limits. A successful checkout followed by a failing pnpm install is the OS setting, not Git, and needs the machine-wide registry value.
Cloning into a synced folder. OneDrive and Dropbox add their own path prefixes, and a deep repository inside them reaches 260 characters sooner than the same repository under C:\src. Sync also locks files during checkout, producing unrelated errors alongside the long path one.
Using --depth 1 to fix a path problem. Shallow clones change history depth, not path length. The checkout still writes the same paths.
Deleting .git/index to reset. That makes Git re-scan the working tree, and the scan is what fails. git reset --hard after the configuration fix is the safe order.
Assuming a 4096-character PATH_MAX on Linux means the same repository is safe. Linux allows the total path to be long but caps each component at 255 bytes, so a single very long file name fails there while the deep tree succeeds. Repositories that work on Windows and fail on Linux are usually this.
Version floor. core.longpaths has been in Git for over a decade; LongPathsEnabled needs Windows 10 1607 or newer; git sparse-checkout set --cone needs Git 2.25 or newer.
The most reliable order is: find the longest paths, move the clone to a short root, enable core.longpaths, then enable the OS setting if anything other than Git still fails. To extract the offending paths from a build log, the regex tester handles the quoted path patterns, and the diff tool shows exactly which files a sparse-checkout change leaves out.
Official references: core.longpaths in the git-config manual and Microsoft's maximum path length limitation.
Official references
primary documentationThe Git documentation that defines the behaviour this guide explains.
Try matching browser tools
All toolsSmall utilities that fit Git work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Git guides
All Git guidesGit: gpg failed to sign the data, and why the commit is not written
No commit is created when signing fails. List the secret keys, expose a TTY, and point Git at the right gpg binary.
Git: SSL certificate problem: self-signed certificate in certificate chain
The browser trusts it and Git does not. Identify the root, keep the public bundle, and avoid the global sslVerify setting that hides the problem.
Git: error: RPC failed; HTTP 413 curl 22 on push
Curl 22 is a wrapper, the status before it is the answer. Separate the client buffer from the proxy and provider limits, then shrink the pack.
Git: fatal: refusing to merge unrelated histories
Two root commits and no merge base. Decide whether to keep both, adopt the remote, or replay your work, then use --allow-unrelated-histories only when the merge is really what you mean.
More in Git
All Git guidesThe guides filed next to this one in Git, in library order.