How to Fix ‘failed to push some refs to’ Git Errors

What is ‘failed to push some refs to’ error

failed to push some refs to is a Git error that many developers frequently face. It occurs when a developer attempts to push committed code to an external git repository, while the local repository has not yet been updated with any changes made in the remote repo. As a result, the ability to push code stops working suddenly, which can be a cause of frustration.

Here are some reasons why the failed to push some refs to error may occur:

• Changes are not committed before pushing
• Issues with Git pre-push hook
• Incorrect branch name
• Local repository not in sync with the Git repository. 

These issues can occur because multiple contributors are working on the same branch and the remote repository is further along than what you currently have on your local machine.

When working in teams, git pushes can overlap, or ref heads could be in different positions. This overlap can cause the repository to be out of sync, which causes a failed to push some refs to error.

To fix this error, you can try these steps (learn more below):

• Run git pull origin to update local branch with changes from remote branch
• Perform rebasing using the git push –rebase origin command
• Use stash to save your local changes

Do not use –force. This is not recommended in most cases.

This is part of a series of articles about Git Errors.

What causes ‘failed to push some refs to’ error

When multiple developers work on the same branch, it can cause a sequencing issue in Git. A commit gets rejected and causes a failed to push some refs to error because the local repository has not been updated with any changes made in the remote repo. In other words, the remote branch contains code that you do not have locally. 

What this means is that your local git repository is not compatible with the remote origin. Git is trying to tell you to update the local repo with the current changes in the remote before pushing your own changes.

Here is an abstraction of what incompatibility looks like in Git:

A -- B -- C -- D (on the remote)
A -- B -- E (on your local machine)

Based on the above, your local machine is missing commits C and D. Meanwhile, you are trying to slot in your commit – E – between B and C on the remote repo.

Before Git lets you proceed, you will need to integrate the remote changes into your local repository. This step will fix any incompatibility issues and ensure that your version is up to date with the remote.

Tips from the expert

Itiel Shwartz

Co-Founder & CTO

Itiel is the CTO and co-founder of Komodor. He’s a big believer in dev empowerment and moving fast, has worked at eBay, Forter and Rookout (as the founding engineer). Itiel is a backend and infra developer turned “DevOps”, an avid public speaker that loves talking about things such as cloud infrastructure, Kubernetes, Python, observability, and R&D culture.

In my experience, here are tips that can help you better handle the “failed to push some refs to” Git error:

Enable pull request reviews:

Implement mandatory code reviews for pull requests to catch conflicts early and avoid last-minute push issues.

Use Git hooks for automation:

Automate sync tasks with Git hooks to ensure your local branch is updated before any push attempt.

Regularly rebase feature branches:

Frequently rebase your feature branches against the main branch to minimize large conflict merges.

Integrate with CI/CD for checks:

Ensure CI/CD pipelines check for branch synchronization before allowing code pushes.

Implement Git workflows:

Use Git workflows like Gitflow or GitHub Flow to structure collaboration and reduce conflicts.

Steps you can try to fix ‘failed to push some refs to’ errors

Here are steps you can take to fix the failed to push some refs error in different scenarios.

1. Run git pull origin to update local branch with changes from remote branch

If another developer pushed a commit to the same branch, and this is the reason for the failed to push some refs error, the error in your terminal will look like this:

To git@git.testdomain.com:sometest.git
! [rejected] your-branch -] your-branch (non-fast-forward)

When this occurs, the head sits at different positions on the same code timeline, and Git does not know how to handle it. This is because the origin repository is ahead of where you currently are. To fix this issue, run git pull on your local repository. This should allow you to push to origin again.

git pull origin [your-branch]
git push origin [your-branch]

You can also use git pull origin master to fetch commits from the origin remote master branch, into the local origin/master branch. Git will then merge origin/master into the branch you currently have checked out.

2. Perform rebasing using the git push –rebase origin command

If you got a master (non-fast-forward) error with a failed to push some refs to error, this means the ref pointer was moved forward in the commit history. However, if your code diverges before it reaches the latest commit, it can cause the non-fast-forward issue and lead to a failed to push some refs to error.

To solve this issue, you can pull with the --rebase flag. --rebase will let you move your intended files to commit over to the latest pull code.

Here is how to pull with --rebase:

git pull --rebase origin [branch]

3. Use stash to save your local changes

If you got a master (fetch first) error with a failed to push some refs to error, this means someone has pushed to the branch before you. Git wants you to pull first before you can push your committed changes.

To prevent the loss of your work during the pull, you can stash your local changes.

Using –force is not recommended in most cases

A common suggested fix is to use --force flag to push through the local changes. However, it is good practice to avoid using the --force flag as it can cause inconsistency issues. Instead, use --rebase to move the ref heads and update your local repository without causing a divergence in the remote repository.

Using --force to try and fix the failed to push some refs to error will only result in more errors in the long run. This occurs because --force uses a brute force method that puts your current code and its ref head as the source of truth.

As a result, the changes in the remote can be overwritten by what you have pushed, removing any features or updates that other developers may have committed.

Only use --force if you are comfortable with features not on your local being overwritten with what you’ve currently got. Use the --force flag if you are confident that your local repository in its current state is correct.

How to prevent ‘failed to push some refs to’ errors

To prevent failed to push some refs to errors in Git, it is good practice to avoid having multiple developers work on the same branch simultaneously. Instead, use feature branches that merge into a master branch or something equivalent.

If you get a failed to push some refs to error, the main thing to do is git pull to bring your local repo up to date with the remote. Avoid employing the --force flag when using git pull and prevent other developers’ accidental overwrites of committed features.

Use the --rebase flag instead to avoid other errors from occurring while fixing your original failed to push some refs to error.

Related content: Read our guide to fatal refusing to merge unrelated histories and fatal remote origin already exists.

Kubernetes Troubleshooting with Komodor

We hope that the guide above helps you better understand the troubleshooting steps you need to fix the failed to push some refs to error.

Keep in mind that this is just one of many Git errors that can pop up in your K8s logs and cause the system to fail. Due to the complex and distributed nature of k8s, the search for the root cause of each such failure can be stressful, disorienting, and time-consuming.

This is why we created Komodor, which acts as a single source of truth (SSOT) to streamline and shorten your k8s troubleshooting processes. Among other features, it offers:

• Change intelligence: Every issue is a result of a change. Within seconds we can help you understand exactly who did what and when.
• In-depth visibility: A complete activity timeline, showing all code and config changes, deployments, alerts, code diffs, pod logs, etc. All within one pane of glass with easy drill-down options.
• Insights into service dependencies: An easy way to understand cross-service changes and visualize their ripple effects across your entire system.
• Seamless notifications: Direct integration with your existing communication channels (e.g., Slack) so you’ll have all the information you need, when you need it.