How to fix error: path contains embedded NUL character in Git

GitADVANCEDHIGHUpdated Dec 2, 2025· 197 views

Git rejects paths containing null bytes (ASCII 0x00) because its internal design uses null-terminated strings. This commonly occurs when files are encoded in UTF-16 or UTF-32 instead of UTF-8.

Quick fix

Fixes error: path contains embedded NUL character

git status
git checkout -- .
  1. Identify the problematic file
  2. Check file encoding
  3. Convert file to UTF-8 encoding
  4. Strip null bytes from files
git — error
git status
git checkout -- .
error: path contains embedded NUL character

What this error means

The "error: path contains embedded NUL character" message indicates that Git has encountered a filename or path containing a null byte (ASCII 0x00, also written as \0). This is a fundamental incompatibility with how Git stores and processes file paths internally. Git's core data structures, written in C, use null-terminated strings to represent file paths in its index (staging area) and tree objects. A null byte signals "end of string" in C, so Git literally cannot store a path that contains a null byte in the middle—the path would appear truncated at that point. This error most commonly surfaces when dealing with files that have been saved in UTF-16, UTF-32, UCS-2, or UCS-4 encodings. These encodings represent ASCII characters using 2 or 4 bytes, padding with null bytes. When Git attempts to interpret such encoded filenames, it sees embedded null characters and correctly rejects them as invalid paths.

Typical symptoms

  • Clone operations fail with "error: path contains embedded NUL character" or "error: invalid path"
  • Checkout fails when switching branches that contain the problematic file
  • Git status shows cryptic or truncated paths
  • Repository works on Linux/macOS but fails on Windows (or vice versa)
  • File appears as binary in git diff despite being text content
  • Git add fails silently or shows path-related errors
  • Repository cloned from another system shows encoding-related path errors

Common causes

  1. File was saved with UTF-16 or UTF-32 encoding, which embeds null bytes between characters
  2. Text file contains actual null bytes in content that Git interprets as path data
  3. Cross-platform repository where files were created with incompatible encoding on another OS
  4. Automated tools or scripts generated files with unexpected character encodings
  5. Copy-paste from applications that use different internal encodings (some Windows apps use UTF-16 internally)
  6. Corrupted file or filesystem issue introduced null bytes into filenames
  7. Repository contains files created on Windows with reserved names like NUL, CON, or COM1
  8. BOM (Byte Order Mark) in filenames being misinterpreted

How to fix "error: path contains embedded NUL character"

1Identify the problematic file

First, determine which file contains the embedded NUL character. Git's error message usually indicates the path:

bash
git status
git checkout -- .

If the error mentions a specific path, note it. If the path appears truncated or garbled, the NUL byte is cutting off the display.

To find files with null bytes in their content:

bash
find . -type f -exec grep -l $'\x00' {} \;
2Check file encoding

Determine the current encoding of the problematic file:

bash
file suspicious-file.txt

This will output something like:
- UTF-8 Unicode text - Good, should work
- UTF-16 Unicode text - Problem! Contains null bytes
- Little-endian UTF-16 Unicode text - Problem!
- data - Binary or corrupted

You can also use hexdump to inspect the raw bytes:

bash
hexdump -C suspicious-file.txt | head -20

Look for patterns of 00 bytes interspersed with text characters, indicating UTF-16 encoding.

3Convert file to UTF-8 encoding

If the file is UTF-16 or another encoding with embedded nulls, convert it to UTF-8:

Using iconv:

bash
iconv -f UTF-16 -t UTF-8 problematic-file.txt > converted-file.txt
mv converted-file.txt problematic-file.txt

Using PowerShell (Windows):

powershell
Get-Content -Path "problematic-file.txt" -Encoding Unicode | Set-Content -Path "converted-file.txt" -Encoding UTF8

Common encoding conversions:

bash
# UTF-16 Little Endian to UTF-8
iconv -f UTF-16LE -t UTF-8 input.txt > output.txt

# UTF-16 Big Endian to UTF-8
iconv -f UTF-16BE -t UTF-8 input.txt > output.txt

# Windows-1252 to UTF-8
iconv -f WINDOWS-1252 -t UTF-8 input.txt > output.txt
4Strip null bytes from files

If the file has actual null bytes embedded (not encoding issues), you can strip them:

bash
# Remove null bytes and convert encoding in one step
tr -d '\0' < problematic-file.txt > cleaned-file.txt
mv cleaned-file.txt problematic-file.txt

Combined approach for stubborn files:

bash
tr -d '\0' < problematic-file.txt | iconv -f WINDOWS-1252 -t UTF-8 > cleaned-file.txt
mv cleaned-file.txt problematic-file.txt

Verify the fix:

bash
file problematic-file.txt
# Should now show: UTF-8 Unicode text
5Use WSL or Git Bash on Windows

If you're on Windows and the repository works elsewhere, try cloning in a different environment:

Using WSL (Windows Subsystem for Linux):

bash
# In WSL terminal
cd /mnt/c/projects
git clone <repository-url>

Using Git Bash:

bash
# Open Git Bash (not PowerShell or cmd)
git clone <repository-url>

WSL and Git Bash handle path encoding differently than native Windows Git, which may work around certain edge cases.

6Fix the file at its source repository

If you're cloning someone else's repository and encountering this error, the fix needs to happen upstream:

1. Report the issue to the repository maintainer with the exact error message
2. Provide details about your OS, Git version, and which file is problematic
3. Suggest they convert the problematic file to UTF-8 encoding

If you have push access:

bash
# Clone on a system where it works (Linux/macOS)
git clone <repo-url>
cd repo

# Find and fix the problematic file
file <problematic-file>
iconv -f UTF-16 -t UTF-8 <problematic-file> > fixed.txt
mv fixed.txt <problematic-file>

# Commit and push the fix
git add <problematic-file>
git commit -m "Convert file encoding to UTF-8 to fix NUL character issue"
git push
7Configure Git to handle encoding issues

Set up Git to better handle encoding scenarios:

bash
# Ensure Git uses UTF-8 for commit messages
git config --global i18n.commitEncoding utf-8
git config --global i18n.logOutputEncoding utf-8

# On Windows, handle line endings properly
git config --global core.autocrlf true

# Display non-ASCII characters properly
git config --global core.quotePath false

Note: These settings help prevent future encoding issues but won't fix existing NUL character problems in tracked files.

Advanced notes

Why Git Cannot Support NUL in Paths:
Git's internal design, inherited from its C implementation, fundamentally relies on null-terminated strings. The index file format, tree objects, and pack files all use NUL bytes as delimiters between path entries. Allowing NUL within a path would break parsing of these core data structures. This is not a bug but a deliberate design constraint that aligns with POSIX filesystem conventions (where NUL is the only character not allowed in filenames).

Understanding UTF-16 and Null Bytes:
UTF-16 represents characters using 16 bits (2 bytes). For ASCII characters (like A-Z, 0-9), the high byte is 0x00 (null). So "hello.txt" in UTF-16 looks like: h\0e\0l\0l\0o\0.\0t\0x\0t\0. When Git reads this, it sees the first null byte after 'h' and interprets the path as truncated or invalid.

Windows-Specific Considerations:
Windows has additional path restrictions enforced by core.protectNTFS. Reserved names like NUL, CON, PRN, AUX, COM1-9, and LPT1-9 are prohibited. The NUL device name specifically can cause confusion—a file literally named "NUL" on Windows is the null device, not a regular file. Git protects against these to ensure cross-platform compatibility.

Prevention Strategies:
- Configure text editors to save in UTF-8 by default
- Use .editorconfig files to enforce encoding: charset = utf-8
- Set up pre-commit hooks to detect non-UTF-8 files:

bash
#!/bin/bash
  for file in $(git diff --cached --name-only); do
    if file "$file" | grep -q "UTF-16\|UTF-32"; then
      echo "Error: $file is not UTF-8 encoded"
      exit 1
    fi
  done

- When working with Windows tools that default to UTF-16 (like PowerShell's Out-File), explicitly specify UTF-8 encoding

Filesystem Encoding vs Content Encoding:
This error specifically concerns path/filename encoding, not file content encoding. Git can store files with any binary content, including null bytes inside the file data. The restriction only applies to the path name used to reference the file in Git's tree structure.

Frequently asked questions

What does "error: path contains embedded NUL character" mean?
The "error: path contains embedded NUL character" message indicates that Git has encountered a filename or path containing a null byte (ASCII 0x00, also written as \0). This is a fundamental incompatibility with how Git stores and processes file paths internally. Git's core data structures, written in C, use null-terminated strings to represent file paths in its index (staging area) and tree objects.
How do I fix "error: path contains embedded NUL character"?
Git rejects paths containing null bytes (ASCII 0x00) because its internal design uses null-terminated strings. This commonly occurs when files are encoded in UTF-16 or UTF-32 instead of UTF-8.
What causes "error: path contains embedded NUL character"?
File was saved with UTF-16 or UTF-32 encoding, which embeds null bytes between characters Text file contains actual null bytes in content that Git interprets as path data Cross-platform repository where files were created with incompatible encoding on another OS
Is the "error: path contains embedded NUL character" 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