How to fix error: path depth exceeds maximum in Git

GitINTERMEDIATEMEDIUMUpdated Dec 2, 2025· 170 views

Git operations fail when file paths exceed system-imposed limits, typically the 260-character Windows MAX_PATH constraint. This affects deeply nested directories and is common with submodules or node_modules on Windows.

Quick fix

Fixes error: path depth exceeds maximum

git config --global core.longpaths true
  1. Enable long paths in Git configuration
  2. Enable long paths in Windows 10/11
  3. Clone to a shorter root path
  4. Use shallow clone for deep submodules
git — error
git config --global core.longpaths true
error: path depth exceeds maximum

What this error means

This error occurs when Git encounters file paths that exceed the maximum path length supported by your operating system or filesystem. While Git itself has no inherent directory depth limitation, it must operate within the constraints of the underlying platform. On Windows, the traditional MAX_PATH limit is 260 characters total for the complete file path (including drive letter, directories, filename, and extension). This legacy limitation dates back to early Windows API design and remains the default behavior for compatibility reasons. When Git tries to create, checkout, or access files with paths exceeding this limit, operations fail with path depth errors. On Linux and Unix systems, while the limits are more generous (typically 4096 characters for total path length and 255 bytes per individual path component), extremely deep nesting can still cause issues. The error manifests most commonly in repositories with deeply nested directory structures, multiple levels of Git submodules, or build artifacts like node_modules that create excessive path depths.

Typical symptoms

  • Git operations fail with "path depth exceeds maximum" error
  • Unable to clone repositories with deeply nested directory structures
  • Checkout or pull commands fail on Windows systems with long paths
  • Repository operations work on Linux/macOS but fail on Windows
  • Error occurs specifically when working with nested submodules or vendor directories

Common causes

  1. Windows MAX_PATH limitation of 260 characters for file paths
  2. Deeply nested directory structures exceeding filesystem limits
  3. Git core.longpaths configuration disabled on Windows systems
  4. Repository containing nested submodules with long path names
  5. Build artifacts or node_modules creating excessive nesting depth
  6. Filesystem-specific path component limits (255 bytes per component on ext4)

How to fix "error: path depth exceeds maximum"

1Enable long paths in Git configuration

On Windows, enable Git's long path support globally:

bash
git config --global core.longpaths true

For system-wide configuration (all users):

bash
git config --system core.longpaths true

This tells Git to handle paths exceeding the traditional 260-character Windows limit.

2Enable long paths in Windows 10/11

On Windows 10 (version 1607+) or Windows 11, enable long path support at the OS level:

Via Registry:

1. Open Registry Editor (regedit)
2. Navigate to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem
3. Set LongPathsEnabled to 1
4. Restart your computer

Via Group Policy (Pro/Enterprise editions):

1. Open Local Group Policy Editor (gpedit.msc)
2. Navigate to Computer Configuration → Administrative Templates → System → Filesystem
3. Open "Enable Win32 long paths"
4. Set to "Enabled"
5. Restart your computer

3Clone to a shorter root path

Reduce the base path length by cloning closer to your drive root:

bash
# Instead of:
# C:\Users\YourName\Documents\Projects\company\team\repo

# Use:
cd C:\
git clone https://github.com/user/repo.git

This reduces the overall path length for all files in the repository.

4Use shallow clone for deep submodules

If the issue involves deeply nested submodules, use shallow cloning:

bash
git clone --depth 1 --shallow-submodules --recurse-submodules <repository-url>

This limits the history depth and can reduce path complexity.

5Flatten directory structure

If you control the repository structure, refactor to reduce nesting:

- Move deeply nested files closer to the root
- Consolidate redundant directory levels
- Use symbolic links for shared resources instead of duplicating nested paths
- Consider restructuring build output directories

For example, instead of:

bash
src/components/features/user/profile/settings/components/forms/inputs/

Use:

bash
src/components/user-profile-settings/

Advanced notes

## Platform-Specific Considerations

Windows:
- The 260-character limit is a legacy Windows API (MAX_PATH) constraint
- Modern Windows (10+) supports up to 32,767 characters when long paths are enabled
- Some applications may still not support long paths even when enabled system-wide
- Git Bash and WSL provide better long path handling than native Windows Git

Linux/Unix:
- No inherent Git directory depth limit beyond system constraints
- ext4 limits individual path components to 255 bytes
- Total path length typically limited to 4096 characters
- Different filesystems (btrfs, xfs) may have different limits

## Git Alternates Depth Limit

Git has a hardcoded limit of 5 levels for nested alternate object stores. This is separate from path depth and typically only affects advanced repository configurations using alternates.

## Build Tool Considerations

Node.js projects with deeply nested node_modules directories are particularly prone to this issue on Windows. Consider:
- Using npm dedupe to flatten dependency trees
- Enabling node-linker=hoisted in pnpm
- Using Yarn's Plug'n'Play mode to avoid node_modules entirely

Frequently asked questions

What does "error: path depth exceeds maximum" mean?
This error occurs when Git encounters file paths that exceed the maximum path length supported by your operating system or filesystem. While Git itself has no inherent directory depth limitation, it must operate within the constraints of the underlying platform. On Windows, the traditional MAX_PATH limit is 260 characters total for the complete file path (including drive letter, directories, filename, and extension).
How do I fix "error: path depth exceeds maximum"?
Git operations fail when file paths exceed system-imposed limits, typically the 260-character Windows MAX_PATH constraint. This affects deeply nested directories and is common with submodules or node_modules on Windows.
What causes "error: path depth exceeds maximum"?
Windows MAX_PATH limitation of 260 characters for file paths Deeply nested directory structures exceeding filesystem limits Git core.longpaths configuration disabled on Windows systems
Is the "error: path depth exceeds maximum" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading