Fixing Git: fatal: the requested upstream branch does not exist

Overview

This error appears when your current local branch has no tracking (upstream) branch configured, or the remote branch it used to track no longer exists. Common triggers:

• Running git pull on a new local branch that hasn’t been pushed
• Remote branch was deleted or renamed
• You’re on a detached HEAD or misconfigured remote

Key idea: each local branch can track a remote branch (the “upstream”). Commands like git pull and git push (without args) rely on that tracking. If it’s missing or gone, you see:

fatal: the requested upstream branch does not exist

Quickstart: the most common fix

If the branch doesn’t exist remotely yet, create it and set tracking in one command:

# From your feature branch
git push -u origin HEAD
# Now future 'git pull' and 'git push' will work without arguments

If the branch already exists on the remote, just link to it:

git branch --set-upstream-to=origin/your-branch

Minimal working example

Reproduce the issue and fix it.

# 1) Create a repo and a new branch
mkdir demo-upstream && cd demo-upstream
git init
printf "hello\n" > README.md
git add README.md
git commit -m "init"
git switch -c feature/demo

# 2) Try to pull (no upstream set yet)
git pull
# -> fatal: the requested upstream branch does not exist

# 3) Fix by pushing and setting the upstream
# First, add a remote (replace URL with a real repo you own)
git remote add origin [email protected]:me/demo-upstream.git

git push -u origin HEAD
# Now upstream is set; pull/push work

git pull   # succeeds

Diagnose and fix in 5 steps

1. Identify your current branch and upstream status

• Show branch and upstream:

  git status -sb     # shows branch and if it tracks something
  git branch -vv     # shows upstream or [gone]
  

• Check the exact upstream:

  git rev-parse --abbrev-ref --symbolic-full-name @{u}
  # errors if no upstream is set
  

1. Inspect remotes and remote branches

git remote -v
git ls-remote --heads origin  # list branch names on 'origin'

1. Decide the intent

• Branch should exist remotely: set upstream to it.
• Branch does not exist remotely: create it via push -u.
• Branch existed but was deleted: either recreate or detach/unset upstream.

1. Apply the appropriate fix

• Create remote branch and set tracking:

  git push -u origin HEAD
  

• Link to an existing remote branch:

  git branch --set-upstream-to=origin/your-branch
  

• Unset a stale upstream:

  git branch --unset-upstream
  

• Refresh remotes and remove stale refs:

  git fetch --all --prune
  

1. Verify

git branch -vv   # shows origin/branch without [gone]
git pull         # should succeed

Common scenarios and commands

Practical patterns

• Always set upstream on first push:

  git push -u origin HEAD
  

• Quickly create a branch that tracks an existing remote branch:

  git fetch origin
  git switch -c feature/x --track origin/feature/x
  # or
  git switch --track -c feature/x origin/feature/x
  

• Re-point an existing branch to a different remote branch:

  git branch --set-upstream-to=origin/new-target
  

Pitfalls and gotchas

• Branch name typos: origin/Feature vs origin/feature are different on some servers; verify with git ls-remote.
• Protected branches and permissions: pushing may be blocked; request access or push to a feature branch.
• Non-default remote: not every repo uses origin. Substitute the correct remote name (e.g., upstream).
• CI environments: shallow or detached checkouts can lack tracking. In jobs, prefer explicit refs:

  git fetch origin main
  git switch -c main --track origin/main
  

• Stale refs: after server-side deletes/renames, run git fetch --prune to avoid [gone] confusion.
• Detached HEAD after clone of a specific commit: create a branch before setting upstream.

Performance and quality-of-life notes

• Use prune to keep refs clean and reduce remote negotiations:

  git fetch --prune --tags
  

• Auto-set upstream on first push (Git 2.37+):

  git config --global push.autoSetupRemote true
  

  With this, git push origin HEAD will automatically set the upstream if it’s not set.
• Prefer HEAD placeholder to avoid branch name typos:

  git push -u origin HEAD
  

• Keep remote names consistent across repos to reduce mistakes (commonly origin for your fork, upstream for canonical).

Tiny FAQ

• Why does git pull fail on a new branch? Because the branch has no upstream yet. Set it with git push -u origin HEAD or link with git branch --set-upstream-to.

• What’s the difference between a remote and an upstream branch? A remote is the repository name (e.g., origin). The upstream branch is the specific remote branch your local branch tracks (e.g., origin/feature/x).

• How do I change the upstream later? git branch --set-upstream-to=origin/other-branch

• How do I remove tracking entirely? git branch --unset-upstream

• How do I find what my branch tracks? git branch -vv or git rev-parse --abbrev-ref --symbolic-full-name @{u}