Fixing Git Push Failures

When you run git push and see an error message, it can be hard to understand what happened at first. This page explains the most common causes of push failures and how to fix them step by step.

Main Causes of Push Failures

Cause 1: The remote has commits that are not on your local machine

If a teammate pushed first, or if you edited files directly on GitHub, the remote is newer than your local copy.

hint: Updates were rejected because the remote contains work that you do not
hint: have locally. This is usually caused by another repository pushing to
hint: the same ref.

In this state, you need to pull the remote changes first.

Cause 2: Tracking information is not set

This happens when the branch tracking relationship between the local branch and the remote branch has not been configured.

There is no tracking information for the current branch.
Please specify which branch you want to merge with.

Fix Steps

Step 1: Set tracking information

Set origin/main on the remote to be tracked by your local main branch.

git branch --set-upstream-to=origin/main main

After this, git pull and git push become simpler.

Check with:

git branch -vv
# main  abc1234 [origin/main] commit message

If you see [origin/main], the setup is correct.

Step 2: Pull the remote changes

Bring the latest changes from the remote into your local repository. The --rebase option places your local commits after the latest remote commits, so no merge commit is created and history stays cleaner.

git pull --rebase origin main

⚠️ If a conflict happens during git pull --rebase, fix the file manually and then run:

git add <fixed-file>
git rebase --continue

If you want to stop the rebase, use git rebase --abort to return to the original state.

Step 3: Push again

After the changes have been applied, run push again:

git push origin main

Your local changes are now reflected on the remote.

Common Errors and Fixes

Error message	Cause	Fix
Updates were rejected because the remote contains work	The remote is newer	git pull --rebase origin main
There is no tracking information	Tracking is not set	git branch --set-upstream-to=origin/main main
Permission denied (publickey)	SSH key is not authenticated	Register the SSH key with GitHub
src refspec main does not match any	You do not have a local main branch	Rename the branch with git branch -M main
fatal: remote origin already exists	origin is already set	Change the URL with git remote set-url origin <URL>

If You Have an Authentication Error (SSH Setup)

If you see Permission denied (publickey), there is a problem with SSH authentication.

# Test SSH connection
ssh -T git@github.com

# Example of a successful result:
# Hi username! You've successfully authenticated.

If the connection fails, you need to generate an SSH key and register it with GitHub. See GitHub Account and SSH Key Setup.

You may also avoid the authentication issue by switching to HTTPS:

git remote set-url origin https://github.com/username/repo.git

Good Habits Before Pushing

To avoid push trouble, make these checks a habit:

# 1. Check the current branch and tracking status
git branch -vv

# 2. Check the difference from the remote
git status

# 3. Check the latest remote info without applying it locally
git fetch origin
git log origin/main --oneline -5

💡 The difference between git fetch and git pull is that fetch only gets remote information and does not apply it to the local branch. pull does fetch + merge (or rebase).

FAQ

Q. Is it okay to use git push -f (force push)?

Force pushing with -f can overwrite someone else’s work on shared branches. Use it only on branches that you alone use, and do not use it on shared branches such as main. If you need a force push, use --force-with-lease instead of -f because it will fail if someone else has already pushed.

Q. Which should I use, git pull or git pull --rebase?

In general, --rebase gives you a straight, easy-to-read history. However, conflict handling is a bit more complex. For beginners, plain git pull is fine.

Q. If a push fails, is my commit lost?

No. The commit is safely saved in your local repository. A push failure only means the remote update failed; it does not affect your local commits.