How to fix error: invalid path 'file<name>.txt' (contains invalid Windows characters) in Git

What this error means

This error occurs when you're working with a Git repository that contains files with characters in their names that Windows does not allow. Windows has strict rules about which characters can appear in file and folder names, while Linux and macOS are much more permissive. The following characters are forbidden in Windows file and folder names: - `<` (less than) - `>` (greater than) - `:` (colon) - `"` (double quote) - `|` (pipe) - `?` (question mark) - `*` (asterisk) - `\` (backslash, except as path separator) - Characters with ASCII values 0-31 (control characters) Additionally, Windows reserves certain names like CON, PRN, AUX, NUL, COM1-COM9, and LPT1-LPT9 regardless of file extension. When you try to check out a branch or clone a repository containing files with these characters, Git on Windows cannot create them and reports this error. This is a common issue when collaborating across operating systems, as developers on Linux or macOS may not realize they've created files that Windows users cannot access.

Typical symptoms

• git checkout fails with 'invalid path' error mentioning Windows characters
• git clone fails partway through when encountering incompatible filenames
• git pull fails after fetching when trying to update the working directory
• Only certain branches fail to check out while others work fine
• Repository works fine on Linux/macOS but fails on Windows
• Error message specifically mentions characters like < > : " | ? *
• CI/CD pipeline fails on Windows agents but passes on Linux
• WSL can access files that native Windows Git cannot

Common causes

1. Repository was created on Linux/macOS with filenames containing < > : " | ? *
2. Automated tools generated files with invalid Windows characters
3. Test fixtures or sample data include characters valid on Unix but not Windows
4. Shell scripts or tools created files with special characters for testing
5. Files imported from other systems without filename sanitization
6. Intentional use of special characters (e.g., in test cases for filename handling)
7. Configuration files with colons (common in some Unix conventions)
8. Downloaded content with preserved original filenames from URLs

How to fix "error: invalid path 'file<name>.txt' (contains invalid Windows characters)"

# On Linux/macOS, find files with Windows-invalid characters
find . -name '*[<>:"|?*]*' -o -name '*[\x00-\x1f]*'

# Using Git to list files in the repository
git ls-files | grep -E '[<>:"|?*]'

# Or check what files would be created during checkout
git diff --name-only HEAD origin/main | grep -E '[<>:"|?*]'

# Check current setting
git config core.protectNTFS

# Enable protection (recommended)
git config core.protectNTFS true

# This setting prevents Git from creating files that would be
# problematic on Windows, even when running on Linux/macOS

# On Linux/macOS or WSL, clone or checkout the repository
git checkout branch-with-problematic-files

# Rename the file to use valid Windows characters
# Replace < > : " | ? * with alternatives like _ - ( )
git mv "file<name>.txt" "file_name.txt"
git mv "test:case.txt" "test-case.txt"
git mv "query?.txt" "query.txt"

# Commit the rename
git commit -m "Rename files to use Windows-compatible characters"

# Push the fix
git push origin branch-name

# Initialize sparse checkout
git sparse-checkout init

# Set patterns to exclude problematic files
git sparse-checkout set '/*' '!path/to/problematic*'

# Or specify exactly what you want to include
git sparse-checkout set 'src/' 'docs/' 'package.json'

# Now checkout should work
git checkout branch-name

# Install WSL (from PowerShell as Administrator)
wsl --install

# After restart, open WSL terminal
wsl

# Clone the repository inside WSL's filesystem (not /mnt/c/)
cd ~
git clone https://github.com/user/repo.git
cd repo

# Work with the repository in WSL
git checkout branch-with-problematic-files

# Mark the file to be skipped during checkout
git update-index --skip-worktree path/to/problematic/file

# Or use assume-unchanged (less recommended)
git update-index --assume-unchanged path/to/problematic/file

# Now checkout should succeed, skipping those files
git checkout branch-name

git update-index --no-skip-worktree path/to/file
git update-index --no-assume-unchanged path/to/file

#!/bin/bash
# Prevent commits with Windows-invalid characters in filenames

# Characters invalid on Windows: < > : " | ? * and control chars
INVALID_CHARS='[<>:"|?*]'

# Check staged files for invalid characters
invalid_files=$(git diff --cached --name-only | grep -E "$INVALID_CHARS")

if [ -n "$invalid_files" ]; then
    echo "ERROR: The following files contain Windows-invalid characters:"
    echo "$invalid_files"
    echo ""
    echo "Please rename these files before committing."
    exit 1
fi

exit 0

chmod +x .git/hooks/pre-commit

Advanced notes

# .gitattributes
# Note: All filenames must be Windows-compatible
# Avoid: < > : " | ? * and control characters

# Find and rename files with invalid characters
find . -name '*[<>:"|?*]*' -print0 | while IFS= read -r -d '' file; do
    # Replace invalid chars with underscores
    newname=$(echo "$file" | sed 's/[<>:"|?*]/_/g')
    if [ "$file" != "$newname" ]; then
        git mv "$file" "$newname"
    fi
done

# Enforce Windows compatibility checks
git config core.protectNTFS true

# Handle line endings
git config core.autocrlf input  # On Linux/macOS
git config core.autocrlf true   # On Windows

# Enable long path support on Windows
git config core.longpaths true

validate-filenames:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - name: Check for Windows-invalid characters
      run: |
        invalid=$(git ls-files | grep -E '[<>:"|?*]' || true)
        if [ -n "$invalid" ]; then
          echo "::error::Files with Windows-invalid characters found:"
          echo "$invalid"
          exit 1
        fi

# Enable long paths in Git
git config core.longpaths true

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

Frequently asked questions

What does "error: invalid path 'file<name>.txt' (contains invalid Windows charact" mean?

This error occurs when you're working with a Git repository that contains files with characters in their names that Windows does not allow. Windows has strict rules about which characters can appear in file and folder names, while Linux and macOS are much more permissive. The following characters are forbidden in Windows file and folder names: - < (less than) - > (greater than) - : (colon) - " (double quote) - | (pipe) - ?

How do I fix "error: invalid path 'file<name>.txt' (contains invalid Windows charact"?

This error occurs when Git encounters a file path containing characters that are invalid on Windows filesystems. Characters like < > : " | ? * cannot be used in Windows filenames, causing checkout failures when repositories created on Linux/macOS contain such files.

What causes "error: invalid path 'file<name>.txt' (contains invalid Windows charact"?

Repository was created on Linux/macOS with filenames containing < > : " | ? * Automated tools generated files with invalid Windows characters Test fixtures or sample data include characters valid on Unix but not Windows

Is the "error: invalid path 'file<name>.txt' (contains invalid Windows charact" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• fatal: cannot create directory: Filename too long. Enable long paths with git config --global core.longpaths true

  How to fix 'fatal: cannot create directory: Filename too long' in Git

  MEDIUM

• error: unable to unlink old 'file.txt': Permission denied

  How to fix 'error: unable to unlink old file: Permission denied' in Git

  MEDIUM

• error: unable to write sha1 filename: Input/output error

  How to fix 'unable to write sha1 filename: Input/output error' in Git

  HIGH

• fatal: CRLF would be replaced by LF in file.txt

  How to fix 'fatal: CRLF would be replaced by LF' in Git

  LOW

• API rate limit exceeded

  How to fix 'API rate limit exceeded' in GitHub

  MEDIUM

• fatal: destination path already exists and is not an empty directory

  Destination Path Already Exists and Is Not Empty

  LOW

Official resources & further reading

• 📚Git Official Documentation
• 📖
  Microsoft Docs - Naming Files, Paths, and Namespaces(Official Docs)
• 📖
  Git Docs - core.protectNTFS configuration(Official Docs)
• 📖
  Git Docs - git-sparse-checkout(Official Docs)
• 💬
  Stack Overflow - Filename issues in Git for Windows(Stack Overflow)
• 📖
  Microsoft Docs - Install WSL(Official Docs)