Fix: error: failed to push some refs to remote

The Error

You run git push and get:

To github.com:user/repo.git
 ! [rejected]        main -> main (fetch first)
error: failed to push some refs to 'github.com:user/repo.git'
hint: Updates were rejected because the remote contains work that you do not
hint: have locally. Integrate the remote changes (e.g., 'git pull ...') before pushing again.

Or variations:

error: failed to push some refs to 'origin'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart.

error: failed to push some refs to 'github.com:user/repo.git'
hint: Updates were rejected because a pushed branch tip is behind its remote counterpart.

remote: error: GH006: Protected branch update failed for refs/heads/main.
error: failed to push some refs to 'github.com:user/repo.git'

Git refused to push your commits to the remote repository. The remote has changes you do not have locally, or something else is blocking the push.

Why This Happens

When you push, Git checks if your local branch can be fast-forwarded onto the remote branch. If the remote branch has commits that your local branch does not, the push fails because it would overwrite those commits.

Common causes:

• Someone else pushed first. A teammate pushed commits to the same branch while you were working.
• You pushed from another machine. Your own commits from a different computer are on the remote.
• Branch protection rules. GitHub/GitLab/Bitbucket branch protection blocks direct pushes.
• Rebased or amended history. You rewrote local history that diverges from the remote.
• Authentication failure. Your credentials expired or are wrong.
• Pre-push hook failure. A Git hook script rejected the push.
• Large file rejection. The remote rejects files exceeding size limits.

Fix 1: Pull Before Pushing

The most common fix. Integrate the remote changes first:

git pull origin main

If there are no conflicts, Git merges the remote changes into your branch. Then push:

git push origin main

If git pull creates a merge commit and you prefer a linear history, use git pull --rebase instead (see Fix 2).

If git pull itself fails because you have uncommitted local changes, see Fix: Your local changes would be overwritten by merge.

Fix 2: Pull with Rebase

For a cleaner history without merge commits:

git pull --rebase origin main

This replays your local commits on top of the remote commits. The result is a linear history.

If conflicts arise during rebase:

# Edit the conflicting files
git add <resolved-files>
git rebase --continue

Then push:

git push origin main

To make rebase the default behavior for git pull:

git config --global pull.rebase true

Pro Tip: Use git pull --rebase as your default workflow. It prevents unnecessary merge commits and keeps the branch history clean. Most teams prefer this over merge-based pulls.

Fix 3: Fix Diverged Branches After Rebase or Amend

If you amended a commit or rebased after already pushing, your local and remote histories have diverged. A regular push fails because the histories are incompatible.

Check the divergence:

git log --oneline --graph HEAD origin/main

Option 1 — Force push (if you are the only one working on the branch):

git push --force-with-lease origin main

--force-with-lease is safer than --force. It fails if someone else pushed to the branch since your last fetch, preventing you from overwriting their work.

Warning: Never force push to shared branches (like main or develop) unless you have coordinated with your team. Force push rewrites remote history and can cause data loss for others. For more on rejected pushes, see Fix: git push rejected non-fast-forward.

Option 2 — Reset to remote and re-apply your changes:

If you are not sure what happened and want to start clean:

git fetch origin
git log --oneline origin/main  # See what's on remote
git log --oneline HEAD         # See what's local

Then decide whether to merge, rebase, or cherry-pick your changes.

Fix 4: Fix Protected Branch Errors

If the error includes GH006: Protected branch update failed or similar:

remote: error: GH006: Protected branch update failed for refs/heads/main.
remote: - Changes must be made through a pull request.

The branch has protection rules that block direct pushes. You need to create a pull request instead:

# Create a feature branch
git checkout -b my-feature

# Push the feature branch
git push -u origin my-feature

# Create a PR on GitHub
gh pr create --title "My changes" --body "Description"

Check branch protection settings:

In GitHub: Settings → Branches → Branch protection rules.

Common protections:

• Require pull request reviews — direct pushes blocked
• Require status checks — CI must pass before merge
• Require signed commits — unsigned commits rejected
• Restrict who can push — only specific users/teams can push

If you are an admin and need to push directly (not recommended):

git push --force-with-lease origin main

Admins can bypass some protections, but this is generally a bad practice.

Fix 5: Fix Authentication Failures

If the error is about authentication:

remote: Invalid username or password.
fatal: Authentication failed for 'https://github.com/user/repo.git'
error: failed to push some refs to 'https://github.com/user/repo.git'

Fix: Update your credentials:

For HTTPS:

# Check your remote URL
git remote -v

# If using HTTPS, update the credential
git credential reject <<EOF
protocol=https
host=github.com
EOF

# Next push will prompt for new credentials
git push origin main

For SSH:

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

# If it fails, check your SSH key
ssh-add -l

If SSH authentication fails entirely, see Fix: git permission denied publickey.

GitHub personal access tokens: If you use HTTPS with GitHub, you need a PAT (Personal Access Token) instead of your password. GitHub stopped accepting passwords in August 2021.

Fix 6: Fix Large File Rejections

GitHub rejects files larger than 100 MB:

remote: error: File large-data.csv is 150.00 MB; this exceeds GitHub's file size limit of 100.00 MB
error: failed to push some refs to 'github.com:user/repo.git'

Fix: Remove the large file from history:

git rm --cached large-data.csv
echo "large-data.csv" >> .gitignore
git commit -m "Remove large file"

If the file was committed in a previous commit, you need to rewrite history:

git filter-branch --force --index-filter \
  "git rm --cached --ignore-unmatch large-data.csv" \
  --prune-empty -- --all

Or use the faster git-filter-repo:

pip install git-filter-repo
git filter-repo --path large-data.csv --invert-paths

Fix: Use Git LFS for large files:

git lfs install
git lfs track "*.csv"
git add .gitattributes
git add large-data.csv
git commit -m "Track CSV with LFS"
git push origin main

Common Mistake: Removing a large file from the working directory and committing the removal does not remove it from Git history. The file still exists in previous commits and the push still fails. You must use filter-branch or filter-repo to rewrite history.

Fix 7: Fix Pre-Push Hook Failures

If a pre-push hook rejects the push:

error: failed to push some refs to 'origin'

The error output usually includes messages from the hook. Common hook checks:

• Running tests before push
• Checking code formatting
• Validating commit messages
• Scanning for secrets or credentials

Find the hook:

cat .git/hooks/pre-push

Or for shared hooks configured by the project:

git config core.hooksPath

Fix the underlying issue (failing tests, formatting errors, etc.) rather than bypassing the hook.

Fix 8: Fix Pushing to a New Remote

If the remote does not exist or the URL is wrong:

# Check the remote URL
git remote -v

# Fix the URL
git remote set-url origin git@github.com:user/repo.git

# Or add a remote if none exists
git remote add origin git@github.com:user/repo.git

If the remote repository itself does not exist, create it first (on GitHub, GitLab, etc.) and then push:

git push -u origin main

The -u flag sets up tracking between your local and remote branch. If you get an error about the remote already existing, see Fix: git remote origin already exists.

Still Not Working?

If the error persists after trying the fixes above:

Check if the remote branch was deleted. If someone deleted the remote branch and recreated it, your local tracking is stale:

git fetch --prune origin
git push origin main

Check for required commit signing. Some repositories require GPG-signed commits. Unsigned commits are rejected:

git log --show-signature -1

If your commit is not signed and signing is required:

git config user.signingkey YOUR_KEY_ID
git commit --amend -S  # Re-sign the last commit

Check for repository transfer or rename. If the repository was moved to a new organization or renamed, update your remote URL.

Check disk space on the remote. Self-hosted Git servers (Gitea, GitLab CE) can reject pushes when disk space is low.

Check the server-side hooks. If the remote runs custom server-side hooks (pre-receive, update, post-receive), they might reject your push for reasons not shown in the client error. Check the server logs or contact the repository administrator.

Try pushing a single commit. If pushing many commits fails, try pushing one at a time to identify which commit is causing the issue:

git push origin HEAD~5:main  # Push all but the last 5
git push origin HEAD~4:main  # Then the next one
# Continue until you find the problematic commit

If you end up in merge conflict during the pull, see Fix: git merge conflict for resolution steps.