Git is essential for deployment workflows, but its error messages can be cryptic. This guide covers the most common Git errors encountered on a VPS during deployment and development work.
"fatal: not a git repository"
cd /correct/path/to/repoYou're running a git command outside an actual git repository directory — verify you're in the correct directory, or that .git exists (wasn't accidentally deleted).
"Permission denied (publickey)"
ssh -T [email protected]SSH key authentication with the git host is failing — verify your SSH key is correctly added to the git hosting service and that ssh-agent has the key loaded (ssh-add -l to check).
"Your branch is behind ... and can be fast-forwarded"
git pullInformational, not an error — simply indicates your local branch has diverged (is behind) the remote; pulling updates it.
Merge Conflicts
git statusShows conflicted files — manually edit each to resolve the conflict markers (<<<<<<<, =======, >>>>>>>), then:
git add resolved-file.txt
git commit"fatal: refusing to merge unrelated histories"
git pull origin main --allow-unrelated-historiesOccurs when merging two genuinely separate repository histories — use this flag deliberately when you actually intend to merge unrelated histories, understanding the merge implications.
Accidentally Committed Sensitive Data
See How to Manage Environment Variables and Secrets on a VPS for prevention; if already committed, simply deleting the file in a new commit isn't sufficient — the sensitive data remains in git history; specific history-rewriting tools exist for proper removal, and the exposed credential should be rotated regardless.
"detached HEAD" State
git checkout mainOccurs when you've checked out a specific commit rather than a branch — return to a proper branch; if you made commits while detached that you want to keep, create a new branch from that state first (git checkout -b new-branch-name) before switching away.
Large File Rejected by Push
remote: error: File too largeMost git hosting services limit individual file size — for genuinely large files, use Git LFS (Large File Storage), or reconsider whether the large file belongs in version control at all versus separate storage.
Deployment-Specific: git pull Fails Due to Local Changes on the Server
git status
git stash
git pull
git stash popIf a deployment server has local uncommitted changes (often accidental, e.g. from a manual edit) conflicting with an incoming pull, stash them temporarily, pull, then decide whether to reapply or discard the stashed local changes.
Fixing a Bad Commit Message (Before Pushing)
git commit --amend -m "Corrected message"Only safe to amend commits that haven't been pushed/shared yet — amending already-pushed commits requires a force push and coordination with anyone else using that branch.
Common Errors
"Updates were rejected because the tip of your current branch is behind" — someone else pushed changes since your last pull; run git pull (resolving any merge conflicts) before pushing your own changes.
Continue Reading
- How to Manage Environment Variables and Secrets on a VPS
- How to Build a Simple CI/CD Pipeline with GitHub Actions
- How to Install Gitea (Lightweight Git Server)
Browse more articles in Troubleshooting & FAQ.
