Git troubleshooting

Merge conflict

Pull or merge stops with conflict markers in files (<<<<<<<, =======, >>>>>>>). Edit files to resolve, then git add each and git commit (or continue rebase with git rebase --continue). Abort with git merge --abort or git rebase --abort. Use git diff and git status to see unmerged paths.

Push rejected (non-fast-forward)

Remote has commits you lack — someone else pushed first, or you rewrote local history. Run git pull --rebase (or git pull then fix conflicts), then push again. Force push (git push --force) overwrites remote history — only on your own feature branches, never on shared main without team agreement.

Authentication failed (HTTPS or SSH)

HTTPS: expired password — use a personal access token instead of account password on GitHub/GitLab. SSH: wrong key, key not in agent, or host key changed — see SSH lab. Test with ssh -T git@github.com. Verify remote URL: git remote -v (HTTPS vs SSH mismatch with your credentials).

Detached HEAD

Checked out a specific commit or tag — not on a branch. New commits are not on any branch until you create one: git switch -c fix-branch or git checkout -b fix-branch. Otherwise commits may become unreachable after you switch away (recover via git reflog).

fatal: index.lock / another git process

Stale lock from interrupted command or concurrent Git processes. Ensure no other git command is running, then remove .git/index.lock only if sure nothing is active. Repeated locks may indicate NFS/sync issues on .git.

Large file / push over limit

GitHub and hosts reject blobs over ~100 MB. Remove from history with git filter-repo or BFG, or use Git LFS before committing binaries. If already committed locally, reset before push or rewrite history (coordinate with team).

Corrupted or missing object

error: object file ... is empty or missing SHA — disk full during write, interrupted fetch, or damaged .git/objects. Try git fsck for diagnosis. Often fastest fix: rename broken repo, fresh git clone, re-apply unpushed work from backup or reflog if objects still exist locally.

Wrong branch or accidental commit on main

Move commits to a branch: git branch feature/x then reset main back (git reset --hard origin/main if not pushed). If already pushed, use git revert on main and cherry-pick to the correct branch.

Debugging workflow

1. State check

git status
git branch -vv
git remote -v
git log --oneline -5

2. Connectivity

git fetch origin
ssh -T git@github.com
git config --list --show-origin | grep -E 'user|remote'

3. Recover lost work

git reflog
git checkout -b recovered HEAD@{2}

Practice scenarios

Hands-on Git scenarios on live Linux VMs: git

Cheatsheet →