Tech & AI, Explained

git-errors

7 min read

Git errors

Status: đŸŸ© COMPLETE Last updated: 2026-06-21 Plain-English tagline: The Git messages that look scary but mean simple things. Paste the fragment, find the fix.

What this is

Git’s error messages have a specific tone — terse, technical, frequently scary. Most of them mean simple things once you decode them. This is the decoder.

For rescue scenarios broader than a single error message, see Git rescue moves đŸŸ©.

“fatal: not a git repository”

What it means: You’re in a folder that isn’t tracked by Git.

Fix:

  • You meant to be elsewhere: cd to the right folder.
  • You meant to start a repo here: git init.
  • The repo exists but the .git folder is missing: something got deleted; re-clone or restore from backup.

”fatal: refusing to merge unrelated histories”

What it means: You tried to merge two branches with no shared commits. Usually happens when you initialize a fresh repo locally, then git pull from a different existing repo.

Fix:

git pull origin main --allow-unrelated-histories

You’ll likely get conflicts on every file. Resolve them, commit. Future pulls work normally.

Better prevention: Always clone first, then add your code. Don’t git init locally and then try to pull from an unrelated remote.

”Your branch is behind ‘origin/main’ by N commits”

What it means: Others (or another machine of yours) pushed commits since your last fetch. Yours doesn’t have them yet.

Fix:

git pull

If that fails because you have uncommitted local changes:

git stash
git pull
git stash pop

“Your branch and ‘origin/main’ have diverged”

What it means: You have local commits the remote doesn’t, AND the remote has commits you don’t. Both sides moved forward independently.

Fix: decide whether to merge or rebase.

git pull                                # default: merge (creates merge commit)
# OR
git pull --rebase                       # rebase your commits onto remote's tip

For solo work, rebase is cleaner. For shared branches, merge is safer.

”Updates were rejected because the tip of your current branch is behind”

What it means: You’re trying to push, but the remote has commits you don’t. Git refuses to overwrite them.

Fix: Pull first, then push.

git pull
# (resolve any conflicts)
git push

Don’t reach for --force here — that overwrites the remote’s commits. Use --force-with-lease only when you genuinely meant to rewrite history (e.g. after a rebase) and you’re the only one on the branch.

”Aborting commit due to empty commit message” / “Please tell me who you are”

What they mean:

  • Empty commit message: the editor closed without a message saved.
  • “Please tell me who you are”: you haven’t set user.name and user.email in Git config.

Fix:

git config --global user.name "George"
git config --global user.email "you@example.com"

For the empty message, just retry with -m:

git commit -m "Your message here"

“fatal: cannot do a partial commit during a merge”

What it means: You’re in the middle of a merge with conflicts, and you tried to git commit <some-file> instead of staging everything.

Fix:

git add <all-conflicted-files>          # not just some
git commit                              # without specifying files

“CONFLICT (content): Merge conflict in ”

What it means: Git couldn’t auto-merge the file. You need to resolve the conflict manually.

Fix:

  1. Open the file. Find the <<<<<<<, =======, >>>>>>> markers.
  2. Edit to be what you want. Delete the markers.
  3. git add <file>.
  4. After all conflicts: git commit (for merge) or git rebase --continue (for rebase).

Reference: Resolving merge conflicts đŸŸ© — full walkthrough.

”error: pathspec ‘X’ did not match any file(s) known to git”

What it means: You referred to a file or branch by a name Git doesn’t recognize.

Common causes:

  • Typo in the file or branch name.
  • File isn’t tracked yet. git checkout file.txt fails on untracked files — use git restore instead, or you need to git add first.
  • Branch doesn’t exist locally. git switch feature/x fails if feature/x is only on the remote. Try git switch -c feature/x origin/feature/x.

”Permission denied (publickey)”

What it means: You’re trying to push/pull via SSH but your SSH key isn’t set up (or isn’t authorized for this repo).

Fix:

  • Generate an SSH key: 
    ssh-keygen -t ed25519 -C "you@example.com"
  • Upload the public key (~/.ssh/id_ed25519.pub) to GitHub → Settings → SSH keys.
  • Test: ssh -T git@github.com should say “Hi !”

Workaround: switch to HTTPS for that remote:

git remote set-url origin https://github.com/u/r.git

“fatal: detected dubious ownership in repository”

What it means: The folder is owned by a different user than the one running Git. Common after copying a project between machines.

Fix:

git config --global --add safe.directory <path>
# Or for any folder:
git config --global --add safe.directory '*'

The latter disables the safety check globally — fine for personal machines, less ideal on shared servers.

”Auto-merging X / CONFLICT (modify/delete)”

What it means: One branch deleted the file; the other modified it. Git can’t decide which you want.

Fix:

# Keep the deletion:
git rm <file>
 
# Keep the modification (restore the file):
git add <file>
 
# Either way, after deciding:
git commit

“could not lock config file .git/config: File exists”

What it means: Another Git process is running (or crashed and left a lock file).

Fix:

# Confirm no other Git process is actually running, then:
rm .git/index.lock      # if it's the index lock
rm .git/config.lock     # if it's the config lock

(On Windows PowerShell: Remove-Item .git\index.lock.)

”You are in ‘detached HEAD’ state”

What it means: You ran git checkout <hash> (or similar) and you’re not on any branch. Commits you make won’t belong to a branch and could be lost.

Fix:

# To stay on this commit but on a branch:
git switch -c rescue-branch
 
# To go back to where you were:
git switch main         # or whatever you came from

If you made commits while detached, git reflog will show them — don’t panic.

Reference: Git rescue moves — “Detached HEAD"

"There is no tracking information for the current branch”

What it means: You ran git pull or git push without arguments, but Git doesn’t know which remote branch to use.

Fix:

# Set the upstream for this branch:
git push -u origin <branch-name>
 
# Or pull explicitly:
git pull origin <branch-name>

“Refusing to delete the current branch”

What it means: You tried git branch -d <branch> while you’re on that branch.

Fix: switch to a different branch first.

git switch main
git branch -d <branch>

”fatal: The current branch X has no upstream branch”

What it means: You tried to git push but this branch was never pushed before. Git doesn’t know where to push to.

Fix:

git push -u origin <current-branch>

The -u (or --set-upstream) tells Git “remember this for next time."

"warning: LF will be replaced by CRLF in ”

What it means: You’re on Windows with core.autocrlf set, and Git is converting line endings.

This is a warning, not an error — Git is doing what you asked. If it’s noisy:

# Confirm your config:
git config --global core.autocrlf
 
# Recommended values:
# Windows: true
# Mac/Linux: input

To suppress the warning specifically:

git config --global core.safecrlf false

“error: failed to push some refs” (with no clearer message)

What it means: Generic push failure. Usually one of:

  • Remote has commits you don’t (most common). → git pull.
  • Pre-receive hook on the remote rejected your push (branch protection rules). → Open a PR instead.
  • Authentication failure. → Re-check gh auth status or your SSH setup.

”fatal: I don’t handle protocol ‘http’”

What it means: You set a remote URL with a typo or bad protocol.

Fix:

git remote -v                               # see current URLs
git remote set-url origin https://github.com/u/r.git

See also

Sources

Graph View

Backlinks