Git Errors — What Went Wrong and How to Fix It
Step-by-step solutions for the most common Git problems — with copy-paste commands
Panic You are in 'detached HEAD' state
This happens when you checkout a commit hash, tag, or remote branch directly instead of a local branch. Any commits you make here are "floating" and can be lost.
- 1Check where HEAD is pointing:
git log --oneline -5- 2If you have no new commits to save, just switch back to your branch:
git checkout main- 3If you made commits you want to keep, create a new branch from here first:
git checkout -b my-recovery-branch- 4Then merge or rebase that branch into main as needed.
git checkout main) rather than commit hashes to avoid detached HEAD.
Panic I need to undo my last commit
There are two safe ways to undo a commit depending on whether you want to keep your changes.
- 1Soft reset — undo the commit but keep changes staged (safest):
git reset --soft HEAD~1- 2Mixed reset — undo the commit and unstage changes (files still modified):
git reset HEAD~1- 3Hard reset — undo the commit AND discard all changes permanently:
git reset --hard HEAD~1--hard permanently deletes your uncommitted changes. There is no undo. Use --soft unless you are certain.
git revert HEAD instead — it creates a new commit that undoes the last one without rewriting history.
Panic I did git reset --hard and lost my work
Don't panic! Git doesn't immediately delete lost commits. You can recover using the reflog.
- 1View the reflog (your HEAD history):
git reflog- 2Find the commit hash before the reset (e.g., abc1234). Then recover:
git checkout -b recovery-branch abc1234Merge CONFLICT (content): Merge conflict in <file>
Git couldn't automatically merge two branches because the same lines were changed differently in each.
- 1See which files have conflicts:
git status- 2Open each conflicted file. Look for conflict markers and edit to keep the correct code:
- 3After editing, mark each file as resolved:
git add src/app.js- 4Complete the merge:
git commitgit mergetool to open a visual diff tool, or use VS Code's built-in merge editor.
Merge Rebase went wrong — how do I abort?
A rebase in progress with conflicts can be safely aborted to restore your branch to its pre-rebase state.
- 1Abort the rebase entirely and go back to where you started:
git rebase --abort- 2Or, if you want to fix conflicts and continue:
git add .git rebase --continue- 3To skip a problematic commit entirely:
git rebase --skipgit rebase --abort is always safe — it fully restores your branch to its original state before the rebase started.
Merge When to use reset vs revert?
Both undo changes, but they work very differently and are suited to different situations.
- 1Use
git revertwhen the commit has already been pushed to a shared branch. It creates a new commit that undoes the changes — safe for team repos:
git revert HEADgit revert <commit-hash>- 2Use
git resetonly on local, unpushed commits. It rewrites history:
git reset --soft HEAD~1git reset on commits that others have already pulled. It rewrites history and will cause conflicts for your teammates.
Remote error: failed to push some refs — push rejected
Someone else pushed to the remote branch since your last pull. You need to integrate their changes first.
- 1Pull the latest changes and merge:
git pull origin main- 2Or pull with rebase for a cleaner history:
git pull --rebase origin main- 3Resolve any conflicts, then push:
git push origin maingit push --force on shared branches. It overwrites others' work. Only use force-push on your own feature branches.
Remote SSL certificate problem: unable to get local issuer certificate
Git can't verify the SSL certificate of the remote server. Common on corporate networks with custom CA certificates or misconfigured Git installs.
- 1Update your CA certificate bundle (preferred fix on Linux/Mac):
git config --global http.sslCAInfo /path/to/ca-bundle.crt- 2On Windows, update Git for Windows to the latest version — it bundles an updated CA store.
- 3If on a corporate network, ask IT for the internal CA certificate and add it to Git's trust store.
- 4Temporary workaround only (not for production):
git config --global http.sslVerify falseRemote fatal: refusing to merge unrelated histories
This happens when you try to merge two branches that have no common commit ancestry (e.g., a new repo with an existing one).
- 1If you are sure you want to merge (e.g., initializing a project with an existing history), use the
--allow-unrelated-historiesflag:
git pull origin main --allow-unrelated-histories- 2Or when merging a branch:
git merge other-branch --allow-unrelated-historiesCommon warning: LF will be replaced by CRLF / CRLF line endings
Windows uses CRLF line endings, Unix/Mac use LF. Git is warning you about automatic conversion. This can cause noisy diffs and cross-platform issues.
- 1On Windows — auto-convert on checkout, commit as LF (recommended for cross-platform teams):
git config --global core.autocrlf true- 2On Linux/Mac — commit as-is, no conversion:
git config --global core.autocrlf input- 3For team consistency, add a
.gitattributesfile to your repo root:
* text=auto eol=lf.gitattributes file overrides individual developer settings and is the most reliable way to enforce consistent line endings across a team.
Common Untracked files cluttering my working tree
Files Git doesn't know about yet. You either want to track them, ignore them, or remove them.
- 1Add files you want to track:
git add <filename>- 2Ignore files permanently by adding them to
.gitignore:
echo "node_modules/" >> .gitignore- 3Preview what would be deleted before cleaning:
git clean -n- 4Remove all untracked files (irreversible):
git clean -fdgit clean -fd permanently deletes files. Always run git clean -n first to preview what will be removed.
Common Stash conflict — cannot apply stash
Your stashed changes conflict with the current state of the working tree. Git can't apply the stash cleanly.
- 1List your stashes to find the right one:
git stash list- 2Try applying with conflict markers instead of popping:
git stash apply stash@{0}- 3Resolve the conflict markers in the affected files, then stage them:
git add src/app.js- 4Once resolved, drop the stash entry:
git stash drop stash@{0}git stash apply instead of git stash pop when you're unsure — it keeps the stash entry until you manually drop it, so you can retry if something goes wrong.
Common Submodule errors — not checked out or dirty
Submodules often get out of sync after switching branches or pulling changes.
- 1Initialize and update all submodules recursively:
git submodule update --init --recursive- 2To update all submodules to their latest remote commit:
git submodule update --remote --merge- 3If submodule has uncommitted changes you want to discard:
git submodule foreach --recursive git reset --hardgit pull, always run git submodule update --init --recursive to sync submodules.
The most common Git errors and exactly how to fix them
Git errors range from mildly confusing to genuinely alarming. Most of them are recoverable — even the ones that look catastrophic. Here are the ones you'll hit most often and the commands that fix them.
Error reference
| Error | What it means | Fix |
|---|---|---|
| rejected — non-fast-forward | Remote has commits your local branch doesn't | git pull --rebase then push |
| CONFLICT (content): Merge conflict | Same lines changed in both branches | Edit conflicted files, remove markers, then git add + git commit |
| HEAD detached at ... | You checked out a commit, not a branch | git checkout -b new-branch-name |
| fatal: not a git repository | Running git outside a repo folder | cd into your project folder first |
| nothing to commit, working tree clean | No staged or unstaged changes | Check git status — you may be on the wrong branch |
| Permission denied (publickey) | SSH key not added to GitHub/GitLab | Run ssh-add ~/.ssh/id_rsa or add key to your Git host |
Undoing things in Git
git commit --amend— fix the last commit message or add a forgotten file (only safe before pushing)git reset HEAD~1— undo last commit, keep changes stagedgit reset --hard HEAD~1— undo last commit, discard changes (destructive)git revert HEAD— safe undo: creates a new commit that reverses the last one (safe to push)git stash— temporarily shelve uncommitted changes so you can switch branches
Complete Developer Toolkit
Git errors often occur alongside other development problems. The first tool to pair with this guide is our Git command cheat sheet — once you understand what went wrong, you need the exact commands to fix it. Our diff checker is invaluable when resolving merge conflicts — paste both versions of a conflicted file to see exactly what changed and decide which lines to keep. The regex tester helps you write git log --grep patterns or .gitignore glob patterns to filter commits or exclude files.
For diagnosing authentication failures when pushing to remote repositories, our Base64 encoder decodes credentials stored in git config, and our SSL expiry checker verifies the HTTPS certificate on your git server. Our DNS lookup confirms your git host domain is resolving correctly when you get connection errors. The Linux terminal cheat sheet covers the shell commands you need when running git in scripts or CI pipelines. Our JSON formatter validates JSON config files in your repo like package.json or CI pipeline configs. For cron-scheduled git jobs, our cron generator builds the schedule expressions correctly.