How to fix error: invalid path 'filename.' - trailing dot not allowed on Windows in Git

GitINTERMEDIATEHIGHUpdated Dec 6, 2025· 247 views

This Git error occurs when cloning or pulling a repository containing files with trailing periods (dots) on Windows. The Windows filesystem API rejects these filenames, causing checkout failures even though Unix-like systems permit them.

Quick fix

Fixes error: invalid path 'filename.' - trailing dot not allowed on Windows

# Clone on a Unix-like system first
git clone <repository-url>
cd <repository>

# Find all files with trailing dots
find . -name "*." -type f

# Or use git ls-tree to see files without checking out
git ls-tree -r --name-only HEAD | grep '\.$'
  1. Identify the problematic files
  2. Rename files on a Unix-like system (recommended)
  3. Use WSL2 as a workaround
  4. Disable core.protectNTFS (not recommended)
git — error
# Clone on a Unix-like system first
git clone <repository-url>
cd <repository>
# Find all files with trailing dots
find . -name "*." -type f
# Or use git ls-tree to see files without checking out
git ls-tree -r --name-only HEAD | grep '\.$'
error: invalid path 'filename.' - trailing dot not allowed on Windows

What this error means

When you encounter this error, Git is trying to create a file whose name ends with a period (dot), such as `config.` or `data.`. While Unix-like operating systems (Linux, macOS) allow trailing dots in filenames, Windows fundamentally does not support them. This limitation exists at the Windows API level. The Win32 `CreateFile()` function automatically strips trailing periods from filenames, making it impossible for Windows to create files like `myfile.` as-is. While NTFS itself can technically store such filenames, the Windows shell and standard APIs reject them. Modern Git versions (2.25.0+) include `core.protectNTFS` enabled by default as a security measure. This setting was introduced in response to CVE-2019-1353, which could allow malicious repositories to exploit path handling differences between operating systems. When Git detects a filename that would be invalid on Windows, it refuses to proceed rather than silently mangling the filename.

Typical symptoms

  • Clone operation fails with 'fatal: unable to checkout working tree' message
  • Pull fails with 'error: invalid path' mentioning a specific filename with a trailing dot
  • Repository works fine on macOS and Linux but fails on Windows
  • CI/CD pipelines using Windows agents fail at checkout step
  • Git GUI clients like GitHub Desktop or SourceTree show checkout errors
  • Error message includes 'not allowed on Windows' or 'path has trailing dot'
  • WSL2 can checkout the repository but native Windows Git cannot

Common causes

  1. Repository contains files created on Unix/Linux/macOS with trailing dots in filenames
  2. Cross-platform team where some developers use macOS/Linux without realizing Windows restrictions
  3. Automated tools or scripts generated files with trailing dots (often config files or temporary files)
  4. Migration from a Unix-based version control system that preserved these filenames
  5. Git's core.protectNTFS security feature blocks the checkout to prevent path manipulation attacks
  6. NTFS filesystem limitation at the Windows API level (not the filesystem itself)
  7. Cloning repositories from projects primarily developed on Unix-like systems
  8. Package dependencies or submodules containing incompatible filenames

How to fix "error: invalid path 'filename.' - trailing dot not allowed on Windows"

1Identify the problematic files

First, determine which files have trailing dots. You can do this from WSL2, a Linux machine, or macOS:

bash
# Clone on a Unix-like system first
git clone <repository-url>
cd <repository>

# Find all files with trailing dots
find . -name "*." -type f

# Or use git ls-tree to see files without checking out
git ls-tree -r --name-only HEAD | grep '\.$'

If you only have Windows available, use WSL2:

bash
# In WSL2 terminal
git clone <repository-url>
find . -name "*." -type f
2Rename files on a Unix-like system (recommended)

The cleanest solution is to rename the problematic files. Do this on Linux, macOS, or in WSL2:

bash
# Example: rename a specific file
git mv "config." "config"

# Or rename with a more descriptive extension
git mv "data." "data.txt"

# Commit the changes
git commit -m "fix: Rename files with trailing dots for Windows compatibility"

# Push to share the fix with the team
git push

If there are many files to rename, you can script it:

bash
# Find and rename all files ending with a dot
find . -name "*." -type f | while read file; do
  newname="${file%.}"  # Remove trailing dot
  git mv "$file" "$newname"
done

git commit -m "fix: Remove trailing dots from filenames for Windows compatibility"
git push
3Use WSL2 as a workaround

If you cannot modify the repository, you can work with it using Windows Subsystem for Linux 2 (WSL2):

bash
# Install WSL2 if not already installed (run in PowerShell as Administrator)
wsl --install

# Open WSL2 and clone the repository there
wsl
cd ~
git clone <repository-url>

Important: Clone into the WSL2 filesystem (/home/username/) rather than the Windows filesystem (/mnt/c/). This gives you full Unix compatibility and better performance.

You can still access and edit these files from Windows:
- VS Code: Use the "Remote - WSL" extension
- File Explorer: Navigate to \\wsl$\Ubuntu\home\username\repo

4Disable core.protectNTFS (not recommended)

Warning: This option has security implications. Only use it temporarily if you fully trust the repository.

You can disable the NTFS protection to allow the checkout:

bash
# Disable protection (security risk!)
git config --global core.protectNTFS false

# Now clone
git clone <repository-url>

# Re-enable protection after cloning
git config --global core.protectNTFS true

Security implications: CVE-2019-1353 exploits path handling differences to perform directory traversal attacks. With core.protectNTFS disabled, a malicious repository could potentially write files outside the working directory.

Even with this disabled, Windows will still mangle the filenames (stripping the trailing dot), which may cause other issues with the repository.

5Use sparse checkout to exclude problematic files

If you don't need the files with trailing dots, use sparse checkout to exclude them:

bash
# Enable sparse checkout
git clone --no-checkout <repository-url>
cd <repository>
git sparse-checkout init --cone

# Include only specific directories (excluding problematic files)
git sparse-checkout set src docs

# Complete the checkout
git checkout

Or explicitly exclude specific patterns:

bash
git sparse-checkout init
echo '/*' > .git/info/sparse-checkout
echo '!problematic-directory/' >> .git/info/sparse-checkout
git checkout

This allows you to work with most of the repository while avoiding the incompatible files.

6Contact repository maintainers

If you don't have write access to the repository, contact the maintainers to request a fix:

Example issue template:

> Title: Files with trailing dots prevent cloning on Windows
>
> Description: The repository contains files ending with periods (e.g., config.), which cannot be checked out on Windows due to filesystem limitations.
>
> Impact: Windows users and CI systems using Windows agents cannot clone or pull this repository.
>
> Suggested fix: Rename the following files to remove trailing dots:
> - path/to/config. -> path/to/config
>
> Reference: Windows API does not support trailing dots in filenames.

Many projects will accept such fixes quickly as they improve cross-platform compatibility.

7Verify the fix

After applying your chosen solution, verify that the repository works on Windows:

bash
# Fresh clone on Windows
git clone <repository-url>
cd <repository>

# Verify all files are present
git status

# Check for any issues with specific files
git ls-files

If you renamed files, ensure the project still builds and tests pass:

bash
# Run your project's test suite
npm test
# or
python -m pytest
# or your project's test command

Advanced notes

### Understanding Windows Path Limitations

Windows has several reserved characters and patterns that are invalid in filenames:

- Trailing dots: file. becomes file (dot stripped)
- Trailing spaces: file becomes file (space stripped)
- Reserved names: CON, PRN, AUX, NUL, COM1-9, LPT1-9
- Reserved characters: < > : " / \ | ? *

This behavior is defined at the Win32 API level in the CreateFile() function, not by NTFS. Technically, NTFS can store these filenames using special APIs (like using \\?\C:\path\file.), but standard Windows tools cannot access them properly.

### Security Context: CVE-2019-1353

Git's core.protectNTFS setting was introduced to address a critical vulnerability. The attack works by:

1. Attacker creates a malicious repository with specially crafted filenames
2. Victim clones the repository on Windows
3. Git's path normalization creates files in unexpected locations
4. Attacker achieves arbitrary file write or code execution

This is why Git refuses to checkout these files rather than silently modifying them - the filename itself could be part of an attack.

### Git Configuration Details

bash
# View current protection settings
git config --get core.protectNTFS
git config --get core.protectHFS    # Similar protection for macOS

# These are enabled by default on their respective platforms
# The setting is checked at checkout time, not at commit time

### Prevention Best Practices

To prevent these issues in your projects:

1. Add pre-commit hooks to reject files with trailing dots:

bash
#!/bin/bash
# .git/hooks/pre-commit
if git diff --cached --name-only | grep -E '\.$'; then
    echo "Error: Staged files have trailing dots (incompatible with Windows)"
    exit 1
fi

2. CI/CD checks - Add Windows to your CI matrix to catch compatibility issues early

3. Documentation - Add a note in your CONTRIBUTING.md about filename restrictions

### Related Error Messages

You might see variations of this error:
- error: invalid path 'filename.'
- error: path 'file.' has trailing dot (not allowed on Windows)
- fatal: unable to checkout working tree
- error: unable to create file 'filename.': Invalid argument

All of these point to the same underlying issue with Windows-incompatible filenames.

Frequently asked questions

What does "error: invalid path 'filename.' - trailing dot not allowed on Windows" mean?
When you encounter this error, Git is trying to create a file whose name ends with a period (dot), such as config. or data.. While Unix-like operating systems (Linux, macOS) allow trailing dots in filenames, Windows fundamentally does not support them.
How do I fix "error: invalid path 'filename.' - trailing dot not allowed on Windows"?
This Git error occurs when cloning or pulling a repository containing files with trailing periods (dots) on Windows. The Windows filesystem API rejects these filenames, causing checkout failures even though Unix-like systems permit them.
What causes "error: invalid path 'filename.' - trailing dot not allowed on Windows"?
Repository contains files created on Unix/Linux/macOS with trailing dots in filenames Cross-platform team where some developers use macOS/Linux without realizing Windows restrictions Automated tools or scripts generated files with trailing dots (often config files or temporary files)
Is the "error: invalid path 'filename.' - trailing dot not allowed on Windows" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading