Fix Git "error: failed to push some refs"

 ! [rejected]        main -> main (fetch first)
error: failed to push some refs to 'github.com:user/repo.git'

Common causes

• Someone else pushed to the branch, so your history is behind (fetch first / non-fast-forward)
• You rewrote local history with rebase or amend after already pushing
• src refspec main does not match any: the branch name is wrong (master vs main) or there are no commits yet
• The branch is protected and requires pull requests or status checks
• A pre-receive hook rejected the push, for example a file over GitHub's 100 MB limit or a detected secret
• You lack write access to the repository or are using the wrong account

How to fix it

1. Read the line before the error. Look for the reason in brackets: (fetch first), (non-fast-forward), (protected branch hook declined) or a remote: error message. Each needs a different fix.
2. Integrate remote changes. For fetch first or non-fast-forward run git pull --rebase origin main, resolve any conflicts, then git push. Use git pull (merge) instead if your team prefers merge commits.
3. Fix the branch name. For src refspec errors run git branch to see your real branch name and push that, such as git push -u origin master. In a new repo, commit at least once before pushing.
4. Force only when you rewrote history on purpose. After an intentional rebase of your own branch, use git push --force-with-lease, which refuses to overwrite commits you have not seen. Never force-push a shared main branch.
5. Use a pull request for protected branches. Push to a new branch with git push -u origin my-fix and open a pull request. Protected branch rules cannot be bypassed from the command line.
6. Remove oversized files from history. If a file is over the host's limit, removing it in a new commit is not enough. Undo the commit with git reset --soft HEAD~1 if it is not pushed, or rewrite history with git filter-repo, and add the file to .gitignore or Git LFS.

Terminal

git pull --rebase origin main
# resolve conflicts, then: git rebase --continue
git push origin main

# after intentionally rewriting your own branch
git push --force-with-lease origin my-branch

How to stop it happening again

• Pull with --rebase before you start work and before you push
• Work on feature branches and merge through pull requests
• Set git config --global pull.rebase true if your team prefers linear history
• Keep large files and backups out of Git with .gitignore or Git LFS