Skip to content
Tutorials Center
My learning

Topics

Lesson 67 of 78 ยท Troubleshooting and Recipes

Troubleshooting: Errors and What They Mean

Decode common Git errors: non-fast-forward, divergent branches, unrelated histories, files would be overwritten, index.lock, safe.directory, line endings, and repairing a corrupted repository.

Git error messages look scary, but they are usually precise. They tell you what Git refused to do, why, and often the exact command that fixes it. The skill is reading them calmly: first the first line (what failed), then the hint lines (what Git suggests), and then your own picture of the repository (where are the branches?).

This lesson reproduces the errors you will meet most often, quotes the real messages from Git 2.56, explains what is happening underneath, and shows the fix. Examples that fail on purpose say so in the title. All of them run against throwaway repositories with local paths standing in for remote servers, and we send stderr into stdout with 2>&1 so the messages appear in order.

A reading checklist. When something fails: (1) read the message from the top, (2) run git status and git log --oneline --graph --all -10, (3) copy the exact error into your notes if you need to ask for help, and (4) do not run commands containing --force or reset --hard until you know what they will discard.

"rejected ... (non-fast-forward)" on push

You try to push, but the remote branch has commits you do not have. Git refuses, because accepting your push would make the remote forget those commits.

Bash Rejected push: non-fast-forward (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The key line is ! [rejected] main -> main (fetch first) or (non-fast-forward), followed by a hint to integrate remote changes with git pull. Which wording you get depends on whether you have fetched the remote commits yet: "fetch first" means you do not even have them locally. The fix is always the same: bring in what the remote has (git pull --rebase or git pull, i.e. fetch plus rebase or merge), resolve any conflicts, and push again. Do not "fix" it with git push --force: that deletes your teammate's commit from the server.

"Need to specify how to reconcile divergent branches"

git pull is a fetch followed by an integration step. When your branch and the remote branch each have commits the other lacks (they have diverged), Git needs to know whether to merge or rebase. Since Git 2.27 it asks you to choose instead of guessing.

Bash Pull with divergent branches (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

You have three options. git pull --rebase replays your commits on top of the remote ones (a straight history). git pull --no-rebase creates a merge commit. git pull --ff-only refuses unless a fast-forward is possible, which is the safest default. Choose once with git config --global pull.rebase true (or pull.ff only) and the message disappears. See Push and Pull and Rebase for the trade-offs.

"refusing to merge unrelated histories"

Two repositories that never shared a commit have no common ancestor, so Git refuses to merge them by default. It usually happens when you git init locally and create the remote with a README, then try to pull.

Bash Unrelated histories (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

git merge-base exits with status 1 and prints nothing when there is no common ancestor, which confirms the diagnosis. --allow-unrelated-histories is the legitimate answer when you really are joining two projects (for example, importing a repository as a subfolder). If it happened because of a README created on the server, it is often easier to start over with a fresh clone.

"Your local changes would be overwritten" / "untracked working tree files would be overwritten"

Git protects uncommitted work. Switching branches or merging fails if it would have to replace a file you changed or a file Git does not track.

Bash Changes would be overwritten (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

For uncommitted edits, the options are: commit them, git stash, or discard them (git restore file) if you do not need them. For untracked files that would be overwritten, Git lists the file names: rename or move your copy, merge, then compare the two versions. Never use git clean -f or git checkout -f here without looking, since those delete exactly what Git was protecting.

"Unable to create '.git/index.lock': File exists"

Git locks its staging area while a command runs by creating .git/index.lock. If a command crashes (or two run at once), the file stays behind, and every later command fails.

Bash A stale index.lock (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The message starts with fatal: Unable to create '.../.git/index.lock': File exists. and continues "Another git process seems to be running in this repository, or the lock file may be stale" (newer Git versions add more advice about removing the file). Always check first that no Git command is really running (an IDE, a GUI client or a background git status from your shell prompt are common culprits), then delete the lock file. The same pattern applies to HEAD.lock, refs/heads/<branch>.lock and packed-refs.lock.

"src refspec main does not match any" and "fatal: not a git repository"

Two short errors with easy causes:

Bash Two easy-to-misread errors (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

  • fatal: not a git repository (or any parent up to mount point /) (older versions say "or any of the parent directories): .git") means you are in the wrong folder, or the .git directory is gone. cd into the project or run git init.
  • error: src refspec main does not match any means there is no local branch called main yet, either because you have no commits or because the branch has another name. Check git branch and make a first commit.
  • error: src refspec master does not match any is the same error for a name you do not have: our branch is main. Mind the difference between the old default master and the newer main.
  • fatal: pathspec 'fiel' did not match any files means the path does not exist (check spelling, and your current directory).
  • fatal: invalid reference: no-such-branch (from git switch) means that name is neither a branch nor a commit.

Line-ending warnings

Windows uses CRLF (\r\n) at the end of text lines, Linux and macOS use LF (\n). If a setting such as core.autocrlf is on, Git converts between them and warns you.

Bash The LF will be replaced by CRLF warning

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The first message is warning: in the working copy of 'notes.txt', LF will be replaced by CRLF the next time Git touches it. It is harmless: it says that your working file will be checked out with CRLF line endings while the repository stores LF. The second one, with input, is the mirror image: dos.txt has CRLF in the working tree and Git stores it with LF (od -c shows only in the stored blob). The last command, git ls-files --eol, shows both sides for each file: i/lf is the line ending in the index, w/crlf the one in your working tree, and attr/text=auto the rule from .gitattributes. The robust, team-wide fix is a .gitattributes file with * text=auto (plus explicit rules for scripts that must stay LF, like *.sh text eol=lf). It is stored in the repository, so everyone gets the same behaviour regardless of their personal core.autocrlf setting. See .gitattributes, Line Endings and Large Files.

"detected dubious ownership" (safe.directory)

Since Git 2.35.2, Git refuses to work in a repository that is owned by a different user than the one running the command, because a malicious .git/config could run programs. You see:

TEXT
fatal: detected dubious ownership in repository at '/srv/app'
To add an exception for this directory, call:

        git config --global --add safe.directory /srv/app

(Read-only: it needs files owned by another user, which the sandbox cannot create.) It typically happens on shared servers, in containers or CI with mounted folders, and on Windows with repositories on other drives or network shares. The fix is exactly what the message says, but only for directories you trust. Do not use safe.directory = * on a multi-user machine, and note that the setting is only read from your user and system config, never from the repository itself.

Authentication and network errors

Without a network we cannot reproduce these, but you will meet them. All of them are about the transport, not about your commits:

Message Usual cause and fix
Permission denied (publickey) The SSH key is not loaded or not registered with the host. Check ssh-add -l and ssh -T git@host.
remote: Support for password authentication was removed / Authentication failed The host needs a personal access token or SSH key, not your account password.
Could not resolve host / Connection timed out DNS, VPN or proxy problem; try ping or curl the host, check http.proxy.
remote: Repository not found / 403 Wrong URL, or you lack access (private repositories often answer "not found" on purpose).
fatal: unable to access ... SSL certificate problem A corporate proxy or an old CA store. Fix the certificates; avoid http.sslVerify=false.
remote: error: File ... is 120 MB; this exceeds the file size limit A large file was committed. Remove it from history or use Git LFS.
! [remote rejected] main -> main (protected branch hook declined) The branch is protected; open a pull request instead of pushing.

See Signing, Credentials and Security for setting up keys and credential helpers.

Repository damage: git fsck and repair

Very rarely, files inside .git are damaged by a full disk, a crash during a write, or a failing drive. git fsck checks the object database for problems. Since every object's name is the hash of its content, Git can prove an object is broken.

Bash Detect and repair a corrupted object

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

In the run, git fsck printed error: inflate: data stream error and missing blob 21a156e... for the damaged file, and exited with status 0 again after the repair. It reports problems such as error: inflate: data stream error or error: hash mismatch, and names the broken object. Typical recovery steps, in order:

  1. Do not panic and do not run git gc (it can discard objects you might still need).
  2. Copy the whole folder somewhere safe first.
  3. Run git fsck --full to list all broken or missing objects.
  4. If you have another copy (a remote, another clone, a backup), delete the broken object file and recreate it from the good copy: git --git-dir=<good copy> cat-file blob <hash> | git hash-object -w --stdin writes the same content back under the same name, which is what the example does. A plain git fetch usually does not help here, because Git believes it already has the commit and does not download the objects below it again. For a badly damaged repository, clone again and copy over your uncommitted work.
  5. If no copy exists, git fsck --lost-found can collect dangling objects, and sometimes the content of a lost blob can be rebuilt from the working tree (git hash-object -w file recreates an object from a file with identical content).
  6. As a last resort, clone from the remote into a new folder and copy your uncommitted work across by hand.

Other warnings from fsck are harmless: dangling commit ... and dangling blob ... just mean unreachable objects, such as commits from an old amend; they are collected by git gc after the reflog entries expire.

Quick reference

Symptom Meaning Typical fix
rejected ... non-fast-forward / fetch first Remote has commits you lack git pull --rebase, then push
Need to specify how to reconcile divergent branches Both sides moved; pull needs a strategy git pull --rebase or set pull.rebase / pull.ff only
refusing to merge unrelated histories No common ancestor --allow-unrelated-histories if intended
local changes would be overwritten Uncommitted edits in the way Commit, stash or restore
untracked working tree files would be overwritten An untracked file is in the way Move it, merge
index.lock: File exists A previous Git process died Verify nothing runs, delete the file
src refspec X does not match any No local branch called X Check git branch; make a commit
not a git repository Wrong folder cd to the project
LF will be replaced by CRLF Line-ending conversion Add .gitattributes with * text=auto
dubious ownership Folder owned by someone else safe.directory for trusted folders
error: object file ... is empty / hash mismatch Corrupt object Copy the folder, refetch the object from a remote
You are in 'detached HEAD' state HEAD points at a commit git switch -c name to keep work

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Your push is rejected with non-fast-forward. What does it mean?

    Git only moves a remote branch forward. If it contains commits you lack, you must integrate them first (pull or fetch plus rebase/merge).
  2. 2. Which is the right response to fatal: Unable to create '.git/index.lock': File exists?

    The lock file is left by a crashed or concurrent Git command. If nothing is really running, removing the file is safe.
  3. 3. What does git merge-base A B printing nothing and exiting with status 1 tell you?

    merge-base prints the best common ancestor. No output and status 1 means none exists, which is what causes 'refusing to merge unrelated histories'.
  4. 4. You see error: src refspec main does not match any when pushing. What is the most likely cause?

    The source side of the refspec (main) names a local ref that Git cannot find. Check git branch and make sure you have at least one commit.
  5. 5. Which tool proves that an object in .git is damaged?

    fsck re-verifies the object database; since an object's name is the hash of its content, a mismatch is proof of corruption.

Summary

  • Read Git errors from the top: what failed, then the hints; then inspect with git status and git log --graph --all.
  • A rejected push means the remote has newer commits: integrate (pull --rebase) and push again, never force.
  • Divergent branches need a strategy: choose --rebase, --no-rebase or --ff-only, or set pull.rebase.
  • Unrelated histories, overwritten files and stale index.lock all protect your work; fix the cause rather than forcing.
  • Line-ending warnings are solved for a whole team with .gitattributes (* text=auto).
  • safe.directory is for directories you trust; authentication errors concern keys and tokens, not commits.
  • git fsck finds damaged objects; copy the folder, delete the bad objects and refetch from another copy.

Next: Repository Maintenance and Performance