What causes "fatal: unable to read config file"?

Missing or deleted configuration file that Git cannot recreate Incorrect file permissions preventing read access (most common on Linux/macOS) HOME environment variable not set or pointing to invalid location (common on Windows)

Is the "fatal: unable to read config file" error serious?

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

How to fix fatal: unable to read config file in Git

GitBEGINNERMEDIUMUpdated Dec 6, 2025· 254 views

This error occurs when Git cannot access its configuration file due to missing files, incorrect permissions, or misconfigured environment variables. The fix depends on which config level is affected.

Quick fix

Fixes fatal: unable to read config file

git config --list --show-origin

Identify which config file is causing the error
Check if the config file exists and has correct permissions
Create missing config file by setting a value
Fix HOME environment variable (Windows)

git — error

$git config --list --show-origin
fatal: unable to read config file

What this error means

When you run a Git command, Git reads configuration settings from up to three levels of configuration files: system-level (`/etc/gitconfig`), global user-level (`~/.gitconfig` or `~/.config/git/config`), and local repository-level (`.git/config`). The "fatal: unable to read config file" error occurs when Git cannot access one of these files. This error typically appears in several scenarios: the configuration file doesn't exist and Git cannot create it, file permissions prevent Git from reading the file, environment variables point to invalid paths (especially on Windows), or a symbolic link points to a non-existent target. On Windows systems, this error is particularly common when the HOME environment variable is not set correctly, or when Git is configured to look for configuration files on a network drive that's currently inaccessible. The error message usually includes the path Git was trying to access, which helps identify which configuration level is affected.

Typical symptoms

Git commands fail with 'fatal: unable to read config file' followed by a path
Error appears when running git config commands or any Git operation
Commands work with sudo but fail without elevated privileges
Error mentions a path with unexpanded environment variables like %HOMEDRIVE%%HOMEPATH%
Git works when connected to VPN but fails when disconnected (network drive issue)

Common causes

Missing or deleted configuration file that Git cannot recreate
Incorrect file permissions preventing read access (most common on Linux/macOS)
HOME environment variable not set or pointing to invalid location (common on Windows)
Symbolic link to .gitconfig pointing to a non-existent file or directory
Configuration file located on an inaccessible network drive
A directory exists where a file is expected (e.g., ~/.gitconfig is a folder instead of a file)

How to fix "fatal: unable to read config file"

1Identify which config file is causing the error

The error message includes the path Git tried to access. Common locations are:

System level: /etc/gitconfig (Linux/macOS) or C:\ProgramData\Git\config (Windows)

Global level: ~/.gitconfig or ~/.config/git/config

Local level: .git/config (inside repository)

To see all config files and their locations:

bash

git config --list --show-origin

This shows every configuration setting along with its source file.

2Check if the config file exists and has correct permissions

Verify the file exists and check its permissions:

bash

# For global config
ls -la ~/.gitconfig

# For local config (run from repo root)
ls -la .git/config

If the file exists but has wrong permissions, fix them:

bash

# Make config file readable and writable by owner
chmod 644 ~/.gitconfig

# For local repository config
chmod 644 .git/config

If the file is owned by root, change ownership:

bash

sudo chown $USER:$USER ~/.gitconfig

3Create missing config file by setting a value

If the config file doesn't exist, Git can create it when you set a configuration value:

bash

# Create global config with your identity
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

For local repository config:

bash

# Initialize or reinitialize the repository
git init

This creates the .git directory and config file if they don't exist.

4Fix HOME environment variable (Windows)

On Windows, Git uses the HOME environment variable to locate ~/.gitconfig. If this variable is missing or incorrect:

Temporary fix (current session):

cmd

SET HOME=%USERPROFILE%

Permanent fix:

1. Open System Properties > Advanced > Environment Variables
2. Under User variables, click "New"
3. Variable name: HOME
4. Variable value: %USERPROFILE% or your actual home path (e.g., C:\Users\YourUsername)
5. Click OK and restart your terminal

PowerShell permanent fix:

powershell

[Environment]::SetEnvironmentVariable("HOME", $env:USERPROFILE, "User")

5Fix broken symbolic links

If ~/.gitconfig is a symbolic link, verify its target exists:

bash

# Check if it's a symlink and where it points
ls -la ~/.gitconfig
readlink ~/.gitconfig

If the target doesn't exist, either:

Option A: Create the target directory and file:

bash

# If symlink points to ~/dotfiles/.gitconfig
mkdir -p ~/dotfiles
touch ~/dotfiles/.gitconfig

Option B: Remove the broken symlink and create a regular file:

bash

rm ~/.gitconfig
git config --global user.name "Your Name"

6Handle network drive issues (Windows)

If Git is configured to look for config on a network drive that's not always available:

Check your Git configuration path:

bash

git config --list --show-origin 2>&1 | head -5

If you see a network path (like H:\ or \\server\share):

1. Ensure you're connected to the network/VPN
2. Or redirect HOME to a local path:

cmd

SET HOME=C:\Users\%USERNAME%

Check Git installation config:

Look at <git-install-path>/etc/profile to see how HOME is being set. You may need to modify this or set HOME before Git reads it.

7Delete stale lock files

If you see "Permission denied" or "File exists" along with the config error, there may be a stale lock file:

bash

# Check for lock files
ls -la ~/.gitconfig.lock
ls -la .git/config.lock

If lock files exist, delete them:

bash

rm -f ~/.gitconfig.lock
rm -f .git/config.lock

Lock files are created during config writes and should be automatically removed. Their presence usually indicates a previous Git operation was interrupted.

8Verify the fix

After applying fixes, verify Git can read its configuration:

bash

# List all configuration
git config --list

# Test a specific config level
git config --global --list
git config --local --list

# Show config files and their locations
git config --list --show-origin

If no errors appear and you see your configuration values, the issue is resolved.

Advanced notes

### Configuration File Hierarchy

Git reads configuration in this order, with later values overriding earlier ones:

1. System (--system): /etc/gitconfig - applies to all users
2. Global (--global): ~/.gitconfig or ~/.config/git/config - your personal settings
3. Local (--local): .git/config - repository-specific settings
4. Worktree (--worktree): .git/config.worktree - worktree-specific (rare)

### XDG Base Directory Support

Git 2.0+ supports XDG Base Directory Specification. If ~/.gitconfig doesn't exist, Git also checks ~/.config/git/config. You can use either location.

### Windows Path Expansion Issues

The error fatal: unable to read config file '%HOMEDRIVE%%HOMEPATH%/.gitconfig' indicates environment variables aren't being expanded. This typically happens when:

- Running Git from a context where environment variables aren't set (scheduled tasks, services)
- The Git installation has incorrect path configuration
- Running "as different user" where the target user's environment isn't loaded

### Git for Windows Installation Check

If issues persist on Windows, verify your Git installation:

bash

# Check Git location
where git

# Check Git version
git --version

# Reinstall if needed - use Git for Windows installer with default settings

### Multiple Git Installations

Having multiple Git installations (Git for Windows, WSL Git, Cygwin Git) can cause conflicts. Ensure your PATH points to the correct Git installation and that HOME is set appropriately for that environment.

Frequently asked questions

What does "fatal: unable to read config file" mean?: git/config). The "fatal: unable to read config file" error occurs when Git cannot access one of these files. This error typically appears in several scenarios: the configuration file doesn't exist and Git cannot create it, file permissions prevent Git from reading the file, environment variables point to invalid paths (especially on Windows), or a symbolic link points to a non-existent target.
How do I fix "fatal: unable to read config file"?: This error occurs when Git cannot access its configuration file due to missing files, incorrect permissions, or misconfigured environment variables. The fix depends on which config level is affected.
What causes "fatal: unable to read config file"?: Missing or deleted configuration file that Git cannot recreate Incorrect file permissions preventing read access (most common on Linux/macOS) HOME environment variable not set or pointing to invalid location (common on Windows)
Is the "fatal: unable to read config file" error serious?: It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading

📚Git Official Documentation
📖
Git - Git Configuration(Official Docs)
📖
Git - git-config Documentation(Official Docs)
📖
Git - First-Time Git Setup(Official Docs)
💬
git config command returns: fatal: unable to read config file '%HOMEDRIVE%%HOMEPATH%/.gitconfig' - Stack Overflow(Stack Overflow)
💬
fatal: unable to access 'H:/.config/git/config': Invalid argument - Stack Overflow(Stack Overflow)
💬
Global git config file does not exist - Stack Overflow(Stack Overflow)
📖
How to fix 'fatal: unable to read config file' error in Git - LabEx(Official Docs)

How to fix fatal: unable to read config file in Git

Quick fix

What this error means

Typical symptoms

Common causes

How to fix "fatal: unable to read config file"

Advanced notes

Frequently asked questions

Related errors

Official resources & further reading