Introduction

This Git error usually appears when the configuration value for init.defaultBranch is empty, malformed, or otherwise not a legal Git branch name. The failure happens during git init, because Git reads that setting to decide what the first branch in a newly created repository should be called.

Core Sections

What init.defaultBranch controls

When you run git init, Git creates a new repository and needs a name for the initial branch. Historically that default was often master. Many current setups use main. The init.defaultBranch setting allows you to choose the name explicitly.

A valid configuration looks like this:

git config --global init.defaultBranch main

If the stored value is blank, corrupted, or contains invalid branch-name syntax, Git cannot create the branch and reports fatal: invalid branch name.

How the bad configuration usually gets introduced

The problem typically comes from one of three places:

• a malformed git config command
• a manually edited .gitconfig file with a broken value
• another configuration scope overriding the expected value

For example, a line that is present but incomplete can cause trouble, as can a value with illegal characters or trailing separators.

The first diagnostic step is to ask Git where the current value is coming from.

git config --show-origin --get init.defaultBranch

This prints both the value and the file that supplied it, which matters because Git merges settings from multiple config scopes.

Set a valid branch name explicitly

The simplest recovery is to replace the bad value with a valid one.

git config --global init.defaultBranch main

You can use another valid branch name if your workflow requires it.

git config --global init.defaultBranch develop

The important part is that the value must satisfy Git’s branch-name rules. For example, it cannot be empty and cannot contain path-like or punctuation patterns that Git rejects.

Unset the broken value if you want a clean reset

If you suspect the current value is garbage or you want to return to Git’s default behavior first, remove the configuration and then re-add it.

git config --global --unset init.defaultBranch

Then verify the current state:

git config --global --get init.defaultBranch

If nothing is returned, the global value is gone and you can set a clean replacement.

Check all configuration scopes when the fix does not stick

Git reads config from several layers:

• system config
• global user config
• repository-local config

If the error persists after updating the global setting, inspect every origin.

git config --list --show-origin | rg 'init.defaultBranch'

That helps identify whether a system-level config file, a bootstrap script, or a repository-local override is reintroducing the invalid value.

A full recovery workflow

A concise recovery sequence looks like this:

1git config --show-origin --get init.defaultBranch
2git config --global --unset init.defaultBranch
3git config --global init.defaultBranch main
4git init

If git init succeeds after that, the issue was the misconfigured setting rather than repository state.

The error text mentions branch names because Git is validating the resulting value, not the configuration key itself. That detail helps narrow the problem quickly.

Common Pitfalls

• Editing only the current repository config misses the real cause if the broken value lives in the global or system config.
• Setting init.defaultBranch to a descriptive string that is not a valid branch name just replaces one invalid value with another.
• Forgetting to inspect the config origin makes it harder to understand why the bad value keeps reappearing.
• Assuming git init itself is broken can send debugging in the wrong direction when the issue is a single malformed config line.
• Fixing the value manually in one file while a setup script rewrites it later leads to recurring failures.

Summary

• The error usually means the configured value of init.defaultBranch is not a legal branch name.
• Use git config --show-origin --get init.defaultBranch to inspect both the value and its source.
• Replace the broken value with a valid branch name such as main.
• Unset the configuration first if you want a cleaner reset path.
• Check all config scopes if the problem survives the first fix.