Something went wrong

Find the message you saw, or the symptom closest to it. Each entry gives the cause, how to confirm it, the fix, and how to avoid it next time.

Authentication and access

1. Authentication failed on push or pull

Cause: the stored credential is wrong or expired, usually a personal access token past its expiry date. Diagnose: git remote -v; an https:// remote uses a token. Fix: create a new token with the right scope, then clear the old credential from the operating system's keychain or credential manager and push again. Prevent: set a calendar reminder for the expiry, or use SSH, which does not expire (lesson 8.4).

2. Permission denied (publickey)

Cause: SSH cannot offer a key the server accepts: no key, the wrong key, or the agent is not running. Diagnose: ssh -T git@gitlab.com or ssh -T git@github.com. Fix: confirm the key exists, add it to the agent with ssh-add, and confirm the public half is on your account. Prevent: one key per machine, added to the account when you set the machine up (lesson 8.2).

3. Repository not found, on a repository you know exists

Cause: usually authentication rather than the URL: you are signed in as someone without access. Diagnose: open the URL in a browser while signed in; check git remote -v for a typo. Fix: correct the credential, or ask for access. Prevent: on a machine with two accounts, set the identity and credential per repository (lesson 18.2).

4. Permission denied to push, but you can read

Cause: you have Read or Reporter access, not Write or Developer. Diagnose: the error names your username and the repository. Fix: ask for the role, saying what you need to do; or fork and open a merge request from the fork. Prevent: ask for the right role when you join (lesson 9.3).

Pushing and pulling

5. Updates were rejected because the remote contains work that you do not have

Cause: someone pushed to that branch since your last fetch. Diagnose: git status -sb shows "behind". Fix: git pull, resolve anything that conflicts, push again. Prevent: pull before you start and before you push (lesson 7.6).

6. non-fast-forward after amending or rebasing

Cause: you rewrote commits the server already has. Diagnose: you ran --amend, rebase, or reset on a pushed branch. Fix: git push --force-with-lease, on your own branch only. Do not follow the hint to pull, which merges the old commits back in. Prevent: rewrite only before pushing (lesson 12.8).

7. --force-with-lease refused: stale info

Cause: the remote branch moved since your last fetch, so the lease check did its job. Diagnose: git fetch then git log --oneline origin/<branch> -3. Fix: look at what arrived. Keep it, then force again, or reconsider entirely. Prevent: fetch before rewriting a pushed branch.

8. You are not allowed to push code to protected branches

Cause: the branch is protected, which is the point. Diagnose: the message names the branch. Fix: git branch <name> to keep the commits, git reset --hard origin/main, then push the branch and open a merge request. Prevent: always start work on a branch (lesson 12.7).

9. Your branch and 'origin/x' have diverged

Cause: both you and the remote have commits the other lacks. Diagnose: git status -sb shows "ahead N, behind M". Fix: git pull to merge, or git pull --rebase to replay yours on top. Both are fine on your own branch. Prevent: pull more often; keep branches short (lesson 7.5).

10. Your local changes would be overwritten by merge

Cause: a pull would change files you have edited. Diagnose: git status lists them. Fix: commit them, or git stash, pull, then git stash pop. Prevent: commit or stash before pulling.

11. A pushed tag does not appear

Cause: git push does not send tags. Diagnose: git ls-remote --tags origin. Fix: git push origin v1.3.0. Prevent: push the tag in the same breath as creating it (command page).

Conflicts and merges

12. CONFLICT (content): Merge conflict in <file>

Cause: both sides changed the same lines. Diagnose: git status lists unmerged paths. Fix: edit the file, remove the markers, git add, git commit. Or git merge --abort to think about it. Prevent: short branches, frequent updates, and talking to whoever owns the file (Section 11).

13. The same conflict, again, in a long rebase

Cause: a rebase replays each commit, so a disagreement recurs per commit. Diagnose: the conflict looks familiar and the rebase is on step 3 of 9. Fix: git rebase --abort and merge instead; or enable rerere first (lesson 18.7). Prevent: rebase early and often, or merge for long branches.

14. commit … is a merge but no -m option was given

Cause: reverting a merge needs to know which side to keep. Diagnose: the commit you are reverting has two parents. Fix: git revert -m 1 <hash>, keeping the first parent, normally the branch you merged into. Prevent: nothing to prevent; the message says exactly what is missing (command page).

15. Conflict markers committed by accident

Cause: the file was staged with <<<<<<< still in it. Diagnose: search the repository for <<<<<<<; the build or the linter usually finds it first. Fix: edit the file properly and commit again. Prevent: read the staged diff before committing (lesson 11.3).

Lost work

16. A commit vanished after git reset --hard

Cause: the branch moved; the commit is unreferenced, not deleted. Diagnose: git reflog, and look for the line describing the state you want. Fix: git reset --hard <hash>, or git reset --hard ORIG_HEAD if it was the last operation. Prevent: git status before any --hard (lesson 12.1).

17. Uncommitted changes are gone

Cause: git restore, git checkout --, a hard reset, or git clean. Diagnose: nothing in Git will show them; they were never recorded. Fix: your editor's local history: IntelliJ's Local History, VS Code's Timeline. Otherwise they are gone. Prevent: commit early; use git stash rather than discarding (lesson 12.9).

18. A deleted branch, and you need it

Cause: git branch -D, which deletes a name. Diagnose: the delete message printed the hash; otherwise git reflog. Fix: git switch -c <name> <hash>. Prevent: use -d, which refuses when the branch is unmerged.

19. You are in 'detached HEAD' state

Cause: you checked out a commit or a tag rather than a branch. Diagnose: git status says "HEAD detached at". Fix: git switch - to leave, or git branch <name> first if you made commits there. Git prints the hash as you leave. Prevent: it is a normal state, not an error (lesson 12.5).

20. Work disappeared after switching branches in an IDE

Cause: VS Code's Stash & Checkout or IntelliJ's Smart Checkout parked it. Diagnose: the Shelf tab, the Stash tab, or git stash list. Fix: unshelve, or git stash pop. Prevent: commit or stash deliberately before switching (lesson 16.6).

Files and the working tree

21. A file keeps reappearing in commits

Cause: it is tracked, and .gitignore does not apply to tracked files. Diagnose: git ls-files <file> prints it. Fix: git rm --cached <file>, add it to .gitignore, and commit both changes. Prevent: write .gitignore before the first commit (lesson 4.3).

22. warning: LF will be replaced by CRLF

Cause: line-ending conversion on Windows. Diagnose: it appears on nearly every file. Fix: it is a warning, not an error. The real fix is a .gitattributes in the repository, agreed with the team. Prevent: .gitattributes from the start (lesson 4.5).

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

Cause: a Git operation was interrupted, or one is genuinely running. Diagnose: check for a running command, another IDE window, or a background fetch. Fix: when nothing is running, delete .git/index.lock, then git status. Prevent: let operations finish; do not force-quit the IDE mid-commit.

24. A file opens as three lines mentioning oid sha256

Cause: the project uses Git LFS and the content was not fetched. Diagnose: .gitattributes lists that file type with filter=lfs. Fix: install Git LFS, git lfs install, then git lfs pull. Prevent: install LFS when you first clone a repository that uses it (lesson 13.10).

Still stuck?

Four things make a question answerable in one reply (lesson 13.9):

1. What you were trying to do, in plain words.
2. The exact command, copied.
3. The exact output, including Git's hints.
4. git status and git log --oneline -3.

And the reassurance worth repeating: a rejected push means nothing was pushed, and a commit you made is almost never really lost.