git configuration_error ai_generated true

fatal: unable to auto-detect email address — git user.email not configured

ID: git/config-email-autodetect

Also available as: JSON · Markdown
99%Fix Rate
98%Confidence
150Evidence
2015-01-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
2 active — — —

Root Cause

Git requires user.name and user.email to be configured before creating commits. Without these, git cannot create commit objects. This error typically appears on first use, in CI environments, or in containers. The fix is straightforward but scope confusion (local vs global vs system) is common.

generic

Workarounds

  1. 99% success Configure git user globally for personal machines 
    Run: 'git config --global user.name "Your Name"' and 'git config --global user.email "[email protected]"'. This sets the identity in ~/.gitconfig for all repositories. Verify with 'git config --global --list'.

    Sources: https://git-scm.com/docs/git-config

  2. 98% success Configure per-repository identity for multi-identity setups 
    Inside the repo, run: 'git config user.name "Work Name"' and 'git config user.email "[email protected]"' (no --global). This stores the identity in .git/config for that repo only. For enforcement, set 'git config --global user.useConfigOnly true' to make git error if no local config exists.

    Sources: https://git-scm.com/docs/git-config

  3. 95% success Use conditional includes for directory-based identity switching 
    Add to ~/.gitconfig: '[includeIf "gitdir:~/work/"]\n  path = ~/.gitconfig-work'. Create ~/.gitconfig-work with '[user]\n  email = [email protected]\n  name = Work Name'. All repos under ~/work/ automatically use the work identity.

    Sources: https://git-scm.com/docs/git-config#_conditional_includes

  4. 97% success Set identity in CI/CD pipelines via environment variables 
    Add to CI config: 'git config user.email "[email protected]"' and 'git config user.name "CI Bot"'. Or set env vars: GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL. GitHub Actions: use 'github-actions[bot]@users.noreply.github.com'.

    Sources: https://git-scm.com/docs/git-config

Dead Ends

Common approaches that don't work:

  1. Setting user.email only at the global level when working on multiple projects with different identities 60% fail

    Global config (~/.gitconfig) applies to all repositories. If you contribute to work and personal projects from the same machine with different email addresses, a single global setting will use the wrong email for some repos. Use per-repo local config or conditional includes instead.

  2. Setting environment variables GIT_AUTHOR_EMAIL without GIT_COMMITTER_EMAIL 70% fail

    Git has separate author and committer fields. If you only set GIT_AUTHOR_EMAIL, the committer will still be unknown. You need to set both GIT_AUTHOR_EMAIL and GIT_COMMITTER_EMAIL (and their NAME counterparts) for full coverage. The git config user.email method sets both at once.

Error Chain

Leads to:
Frequently confused with: