Version Control | VoidX Academy

Common Git Errors & How to Fix Them

Troubleshooting

Common Git Errors & How to Fix Them

Every developer — from first-timers to 10-year veterans — hits these errors. Knowing exactly what each error message means and the one command to fix it is what separates a developer who panics from one who solves it in 30 seconds and moves on.

❌ Error 1: "Please tell me who you are"

Full message: Author identity unknown [...] Please tell me who you are.

Why it happens: You installed Git on a new machine but haven't configured your name and email yet. Git refuses to create a commit without author identity.

Fix:

git config --global user.name "Your Full Name"
git config --global user.email "you@example.com"

Then retry your commit.

❌ Error 2: "fatal: not a git repository"

Full message: fatal: not a git repository (or any of the parent directories): .git

Why it happens: You ran a git command in a folder that Git is not tracking — there's no hidden .git folder here.

Fix — Option A: Navigate to the correct project folder:

cd /path/to/your/project
git status

Fix — Option B: Initialise Git in this folder if it's a new project:

git init

❌ Error 3: "nothing to commit, working tree clean"

Why it happens: You ran git commit but either haven't made any changes, or you forgot to git add first.

Fix: Check what state your files are in, then stage them:

git status          # See which files changed
git add .           # Stage everything
git commit -m "your message"

❌ Error 4: "rejected — non-fast-forward"

Full message: ! [rejected] main -> main (non-fast-forward)

Why it happens: A teammate pushed commits to GitHub that you don't have locally. GitHub refuses to accept your push because it would overwrite their work.

Fix:

git pull            # Download and merge their commits first
# Resolve any conflicts if they appear
git push            # Now GitHub accepts your push

⚠️Never use git push --force to bypass this on a shared branch. That would overwrite your teammate's commits permanently.

❌ Error 5: "CONFLICT — Automatic merge failed"

Full message: CONFLICT (content): Merge conflict in src/app.js — Automatic merge failed; fix conflicts and then commit the result.

Why it happens: You and a teammate edited the same lines of the same file. Git cannot decide which version to keep — it needs a human decision.

Fix (step by step):

git status # Shows you which files have conflicts

Open the conflicted file. Find the conflict markers and choose which code to keep:

<<<<<<< HEAD
  const API_URL = "https://prod.api.com";
=======
  const API_URL = "https://staging.api.com";
>>>>>>> feature/switch-env

Delete the markers and keep the correct version. Then finish:

git add src/app.js
git commit -m "fix: resolve merge conflict in API URL config"

❌ Error 6: "Your branch is ahead of 'origin/main' by N commits"

Why it happens: You've made local commits that haven't been pushed to GitHub yet. This is not technically an error — it's Git informing you of the difference.

Fix:

git push # Upload your local commits to GitHub

❌ Error 7: "Your branch is behind 'origin/main' by N commits"

Why it happens: Teammates pushed commits to GitHub that you haven't downloaded yet. Your local branch is outdated.

Fix:

git pull # Download and apply the new commits

❌ Error 8: "Permission denied (publickey)"

Full message: git@github.com: Permission denied (publickey). fatal: Could not read from remote repository.

Why it happens: Git is trying to authenticate with GitHub via SSH, but either your SSH key isn't set up, or the public key hasn't been added to your GitHub account.

Fix:

# Step 1: Check if you have an SSH key
ls ~/.ssh

# Step 2: If no key exists, generate one
ssh-keygen -t ed25519 -C "you@example.com"

# Step 3: Copy the PUBLIC key
cat ~/.ssh/id_ed25519.pub

# Step 4: Go to GitHub → Settings → SSH Keys → New SSH Key → paste it

# Step 5: Test the connection
ssh -T git@github.com

❌ Error 9: "error: failed to push some refs — Updates were rejected"

Why it happens: Usually the same as Error 4 (non-fast-forward), but can also happen if you're pushing a new branch for the first time without setting the upstream.

Fix for new branch:

git push -u origin your-branch-name

Fix if you need to sync first:

git pull --rebase
git push

❌ Error 10: Detached HEAD State

Full message: HEAD detached at abc1234

Why it happens: You ran git checkout on a specific commit hash or tag instead of a branch name. Git is no longer on any branch — you're floating in history.

Fix — go back to main:

git checkout main

Fix — if you made commits in detached HEAD and want to keep them:

git checkout -b rescue/my-work   # Create a new branch to save your commits
git checkout main
git merge rescue/my-work

💡Detached HEAD is not data loss — your commits still exist. Just create a branch to give them a home before switching away.

Common Git Errors & How to Fix Them

Troubleshooting

Common Git Errors & How to Fix Them

❌ Error 1: "Please tell me who you are"

Full message: Author identity unknown [...] Please tell me who you are.

Why it happens: You installed Git on a new machine but haven't configured your name and email yet. Git refuses to create a commit without author identity.

Fix:

git config --global user.name "Your Full Name"
git config --global user.email "you@example.com"

Then retry your commit.

❌ Error 2: "fatal: not a git repository"

Full message: fatal: not a git repository (or any of the parent directories): .git

Why it happens: You ran a git command in a folder that Git is not tracking — there's no hidden .git folder here.

Fix — Option A: Navigate to the correct project folder:

cd /path/to/your/project
git status

Fix — Option B: Initialise Git in this folder if it's a new project:

git init

❌ Error 3: "nothing to commit, working tree clean"

Why it happens: You ran git commit but either haven't made any changes, or you forgot to git add first.

Fix: Check what state your files are in, then stage them:

git status          # See which files changed
git add .           # Stage everything
git commit -m "your message"

❌ Error 4: "rejected — non-fast-forward"

Full message: ! [rejected] main -> main (non-fast-forward)

Why it happens: A teammate pushed commits to GitHub that you don't have locally. GitHub refuses to accept your push because it would overwrite their work.

Fix:

git pull            # Download and merge their commits first
# Resolve any conflicts if they appear
git push            # Now GitHub accepts your push

⚠️Never use git push --force to bypass this on a shared branch. That would overwrite your teammate's commits permanently.

❌ Error 5: "CONFLICT — Automatic merge failed"

Full message: CONFLICT (content): Merge conflict in src/app.js — Automatic merge failed; fix conflicts and then commit the result.

Why it happens: You and a teammate edited the same lines of the same file. Git cannot decide which version to keep — it needs a human decision.

Fix (step by step):

git status # Shows you which files have conflicts

Open the conflicted file. Find the conflict markers and choose which code to keep:

<<<<<<< HEAD
  const API_URL = "https://prod.api.com";
=======
  const API_URL = "https://staging.api.com";
>>>>>>> feature/switch-env

Delete the markers and keep the correct version. Then finish:

git add src/app.js
git commit -m "fix: resolve merge conflict in API URL config"

❌ Error 6: "Your branch is ahead of 'origin/main' by N commits"

Why it happens: You've made local commits that haven't been pushed to GitHub yet. This is not technically an error — it's Git informing you of the difference.

Fix:

git push # Upload your local commits to GitHub

❌ Error 7: "Your branch is behind 'origin/main' by N commits"

Why it happens: Teammates pushed commits to GitHub that you haven't downloaded yet. Your local branch is outdated.

Fix:

git pull # Download and apply the new commits

❌ Error 8: "Permission denied (publickey)"

Full message: git@github.com: Permission denied (publickey). fatal: Could not read from remote repository.

Why it happens: Git is trying to authenticate with GitHub via SSH, but either your SSH key isn't set up, or the public key hasn't been added to your GitHub account.

Fix:

# Step 1: Check if you have an SSH key
ls ~/.ssh

# Step 2: If no key exists, generate one
ssh-keygen -t ed25519 -C "you@example.com"

# Step 3: Copy the PUBLIC key
cat ~/.ssh/id_ed25519.pub

# Step 4: Go to GitHub → Settings → SSH Keys → New SSH Key → paste it

# Step 5: Test the connection
ssh -T git@github.com

❌ Error 9: "error: failed to push some refs — Updates were rejected"

Why it happens: Usually the same as Error 4 (non-fast-forward), but can also happen if you're pushing a new branch for the first time without setting the upstream.

Fix for new branch:

git push -u origin your-branch-name

Fix if you need to sync first:

git pull --rebase
git push

❌ Error 10: Detached HEAD State

Full message: HEAD detached at abc1234

Why it happens: You ran git checkout on a specific commit hash or tag instead of a branch name. Git is no longer on any branch — you're floating in history.

Fix — go back to main:

git checkout main

Fix — if you made commits in detached HEAD and want to keep them:

git checkout -b rescue/my-work   # Create a new branch to save your commits
git checkout main
git merge rescue/my-work

💡Detached HEAD is not data loss — your commits still exist. Just create a branch to give them a home before switching away.

Common Git Errors & How to Fix Them

Common Git Errors & How to Fix Them

❌ Error 1: "Please tell me who you are"

❌ Error 2: "fatal: not a git repository"

❌ Error 3: "nothing to commit, working tree clean"

❌ Error 4: "rejected — non-fast-forward"

❌ Error 5: "CONFLICT — Automatic merge failed"

❌ Error 6: "Your branch is ahead of 'origin/main' by N commits"

❌ Error 7: "Your branch is behind 'origin/main' by N commits"

❌ Error 8: "Permission denied (publickey)"

❌ Error 9: "error: failed to push some refs — Updates were rejected"

❌ Error 10: Detached HEAD State

Knowledge Check

Common Git Errors & How to Fix Them

Common Git Errors & How to Fix Them

❌ Error 1: "Please tell me who you are"

❌ Error 2: "fatal: not a git repository"

❌ Error 3: "nothing to commit, working tree clean"

❌ Error 4: "rejected — non-fast-forward"

❌ Error 5: "CONFLICT — Automatic merge failed"

❌ Error 6: "Your branch is ahead of 'origin/main' by N commits"

❌ Error 7: "Your branch is behind 'origin/main' by N commits"

❌ Error 8: "Permission denied (publickey)"

❌ Error 9: "error: failed to push some refs — Updates were rejected"

❌ Error 10: Detached HEAD State

Knowledge Check