How to Fix Git Push Rejected Error: A Complete Troubleshooting Guide

Picture this: It is Friday afternoon. You have been grinding on a complex feature all week. The code is clean, the tests pass, and you are ready to push your branch to the remote repository and wrap up the week. You type git push origin main, hit Enter, and instead of the satisfying flow of objects being compressed and uploaded, you are met with a wall of red text.

The dreaded [rejected] error.

If you are searching for exactly how to fix git push rejected error scenarios, take a deep breath. You are in the right place. As a senior developer, I have seen this error haunt everyone from junior devs on their first day to seasoned architects. A rejected push is not a failure; it is Git’s way of telling you that the remote repository has evolved since you last synced, or that a specific rule is being enforced.

In this comprehensive troubleshooting guide, we are going to dissect the root causes of this error, walk through step-by-step solutions (from the most common scenarios to rare edge cases), and arm you with the preventative habits needed to avoid it in the future.

Understanding the Root Cause of a Rejected Push

Before we start fixing things, it helps to understand why Git rejects a push. Git is designed to never intentionally lose data. When you try to push your local commits to a remote branch (like main or develop), Git checks to ensure your local history is a direct, linear descendant of the remote history.

If the remote branch has commits that your local branch does not have, Git rejects your push. It does this to prevent you from accidentally overwriting someone else’s work.

When you run into this, Git will usually output something that looks like this:

! [rejected]        main -> main (non-fast-forward)
error: failed to push some refs to 'git@github.com:username/repository.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.

Essentially, your local timeline and the remote timeline have diverged. To fix this, we need to reconcile those timelines.

Scenario 1: Non-Fast-Forward Updates (The Most Common Culprit)

The vast majority of the time, this error happens because someone else on your team pushed code to the same branch while you were working locally. Your local main branch is now “behind” the remote main branch.

Solution A: Git Pull with Rebase (The Cleanest History)

When looking at how to fix git push rejected error messages, the cleanest approach is usually a rebase. Standard git pull creates a merge commit, which can clutter your project’s history. Pulling with --rebase takes your local commits, temporarily removes them, updates your branch with the remote commits, and then replays your local commits on top.

Step 1: Fetch and Rebase
Run the following command in your terminal:

git pull --rebase origin main

Step 2: Resolve Conflicts (If Any)
If your changes overlap with the changes your teammates pushed, Git will pause the rebase and ask you to resolve merge conflicts.

Open your code editor, find the files with conflicts (usually marked with <<<<<<< HEAD and >>>>>>>), and fix them.

Once resolved, stage the files and continue the rebase:

git add .
git rebase --continue

Note: Do not run git commit during a rebase unless specifically instructed. Just add the files and continue.

Step 3: Push Your Changes
Now that your local branch is perfectly synced with the remote, push your code:

git push origin main

Solution B: Git Pull with Merge (The Default Approach)

If your team prefers a explicit record of when branches were synced (a merge commit), you can use the default pull behavior.

git pull origin main

This will fetch the remote changes and create a new “merge commit” tying your local history and remote history together. If there are conflicts, resolve them in your editor, save the file, stage it, commit it, and finally run git push origin main.

Solution C: Force Pushing (Proceed with Extreme Caution)

Sometimes, you know you want to overwrite the remote history. This is common when you are working alone on a feature branch, or when you are updating an open-source fork and want to completely sync it with the upstream repository.

If you are wondering how to fix git push rejected error logs on a branch you alone control, you can force push:

git push -f origin my-feature-branch

Warning: Never force push to shared branches like main, master, or develop. Overwriting shared history will cause massive headaches for your teammates and can permanently delete commits.

If you want to be slightly safer, use the --force-with-lease flag. This will only force push if no one else has added new commits to the remote branch since your last fetch:

git push --force-with-lease origin my-feature-branch

Scenario 2: Remote Rejected (Branch Protection Rules)

In modern development workflows, pushing directly to main is often disabled. Platforms like GitHub, GitLab, and Bitbucket allow repository administrators to set up “Branch Protection Rules.”

If you try to push to a protected branch, your push will be rejected with a specific message, often mentioning GH006 or similar server-side error codes.

Example error:

remote: error: GH006: Protected branch update failed for refs/heads/main.
remote: error: Changes must be made through a pull request.
 ! [remote rejected] main -> main (protected branch hook declined)

The Fix: Create a Feature Branch and a Pull Request

You cannot force your way past branch protection rules (unless you are an admin with bypass permissions). The proper solution is to use the Git branching workflow.

Step 1: Create a new branch
Ensure you are on the updated main branch, then create a new feature branch:

git checkout main
git pull origin main
git checkout -b feature/new-login-system

Step 2: Commit and Push the Branch
Make your changes, stage them, commit them, and push the new branch to the remote:

git add .
git commit -m "feat: implement new login system"
git push -u origin feature/new-login-system

(Note: The -u flag sets the upstream tracking reference. The next time you are on this branch, you can just type git push and Git will know where to send it).

Step 3: Open a Pull Request
Navigate to your GitHub/GitLab repository in your browser. You will see a prompt to “Compare & pull request.” Click it, fill out the PR template, and let your team review the code before merging it into main.

Scenario 3: Pre-Receive Hook Declined (Server-Side Policies)

Sometimes, your code is rejected not because of branch protection, but because of server-side hooks. Companies often set up automated checks that run the moment you push. If your code fails these checks, the push is rejected.

Common reasons include:
* Commit messages failing a regex pattern (e.g., not conforming to Conventional Commits).
* Commit author email not matching your company email domain.
* Pushing secrets (like AWS keys) detected by scanning tools.

Example error:

remote: Resolving deltas: 100% (3/3), completed with 3 local objects.
remote: ERROR: commit abc1234: email address j.doe@gmail.com is not allowed.
remote: Committer must use a corporate email address.
To github.com:company/project.git
 ! [remote rejected] main -> main (pre-receive hook declined)

The Fix: Rewriting Commit Metadata or Correcting Errors

If the hook rejected your push because of an invalid email address or a poorly formatted commit message, you need to rewrite your local commits before pushing again.

To fix the last commit’s author details:

git commit --amend --author="John Doe <john.doe@company.com>"

To fix a bad commit message:

git commit --amend -m "fix: correct typo in user authentication"

If you have multiple commits with the wrong email, you will need to use an interactive rebase to change them all:

git rebase -r HEAD~3 --exec 'git commit --amend --reset-author --no-edit'

This command takes the last 3 commits and resets the author to your current global Git configuration without changing the commit message. Once the metadata is clean, you can push successfully.

Scenario 4: Large Files Exceeding Limits

Git is designed to track text-based source code. It struggles with massive binary files (like database dumps, uncompressed videos, or large zip archives). If you attempt to push a file exceeding your Git hosting provider’s limit (GitHub has a strict 100MB limit, for instance), the push will fail.

Example error:

remote: error: File sql/dataset.sql is 152.67 MB; this exceeds GitHub's file size limit of 100.00 MB
remote: error: GH001: Large files detected.
 ! [remote rejected] main -> main (pre-receive hook declined)

The Fix: Remove the File from History and Use Git LFS

Simply deleting the file and committing the deletion will not work. The large file still exists in your Git history. Git remembers everything.