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

GitADVANCEDHIGH

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 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.

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.

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

What this error means

Typical symptoms

Common causes

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

Advanced notes

Related errors

Official resources & further reading