Two git errors on Windows that look alike and aren't

Two git errors stop a Windows checkout cold and look like the same complaint. One says the filename is too long. The other says the path is invalid. Both read as "Windows hates your repo," both have a one-line fix sitting at the top of a Stack Overflow thread, and both fixes work in the sense that the checkout completes afterward.

The difference is that one of those one-liners raises a limit and the other switches off a security check. If you paste them interchangeably because they both made the red text go away, you'll eventually paste the wrong one into a place you care about.

"Filename too long": a limit, not a bug

This one is honest about what it is. A checkout dies with:

error: unable to create file <path>: Filename too long

The cause is the old Win32 MAX_PATH ceiling of 260 characters. Plenty of repos built on Linux or macOS carry paths longer than that without anyone noticing, because neither OS cares. Pull the same tree down on Windows and git can't create the file. It's not corruption and it's not git's fault. It's a constraint the platform carried for decades.

You have two ways out, and they operate at different layers.

Raise it in Windows itself. On Windows 10 and Server 2016 (version 1607) and later, the MAX_PATH limit can be lifted, but you have to opt in. Set the registry value and you're done at the OS level:

New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
  -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

Or raise it in git. This works on older Windows too, and it's the one most people reach for:

git config --system core.longpaths true

That lets git handle paths up to roughly 4096 characters. Git disables it by default on purpose, because a repo full of 300-character paths will check out fine and then trip Explorer, cmd, bash, or an IDE that never learned to cope. So understand what core.longpaths buys you: git stops choking, but nothing downstream is obligated to follow. The checkout succeeding is not the same as your editor or your build being able to open the files.

One gotcha worth knowing before you debug it the hard way: some setups ignore --system and only respect --global. If the system-level flip seems to do nothing, switch it:

git config --global core.longpaths true

And if this is biting your CI rather than your laptop, remember the fix lives on the machine that runs the build, not on the server orchestrating it. A Bamboo or Jenkins controller handing work to a pool of Windows agents needs core.longpaths set on every agent that might pick up the job. Set it on one of five and you've bought yourself an intermittent failure that only shows up when the scheduler routes unluckily.

"Invalid path": a guard, not a limit

This one fails differently:

error: invalid path '<path>'

Search it and the top answer is one line:

git config core.protectNTFS false

It works. It's also the wrong reflex, and it's worth slowing down for.

core.protectNTFS exists to refuse paths that NTFS would silently reinterpret. Trailing dots and spaces that Windows strips. Reserved device names like CON, PRN, AUX, and NUL. And the reason the check is on by default at all: the .git masquerade attack, where a crafted path uses an NTFS short name or an alternate data stream to sneak a write into your .git directory during checkout. That's not a hypothetical Windows quirk. It's the specific class of exploit the guard was added to block.

So when you set protectNTFS false, you're not fixing a path. You're telling git to stop checking a category of paths it refuses for a reason, globally, on every repo that config touches.

The path it tripped on is almost always boring: a file committed on Linux or macOS with a name Windows simply can't represent. A colon in the filename. A trailing dot. One of the reserved words. The right fixes, in order:

1. Rename the file upstream. If the repo is yours, fix it at the source so nobody on Windows hits it again. This is the actual fix.
2. Sparse-checkout around it. If you don't need that path on Windows, exclude it and never materialize the offending file at all.
3. Only then, if you must have it and you trust the repo, flip protectNTFS off, complete the checkout, and flip it back. Scope it to the one repo, not your global config.

The reflexive global disable is how a guardrail meant to stop a .git write attack ends up permanently off on a developer's machine because of one annoying filename three years ago.

The thing to remember

These two errors share a terminal and nothing else. "Filename too long" is a ceiling Windows held onto too long, and raising it is a clean call. "Invalid path" is git protecting you from names that NTFS would quietly twist, and switching that off should feel different than switching off a length limit, because it is.

Reach for core.longpaths without thinking twice. Reach for core.protectNTFS false knowing exactly what you turned off, and turn it back on when you're done.