git push fatal: The current branch has no upstream branch
No upstream branch set for the current branch
Verified against git 2.47 docs (git-push.html), Stack Overflow #6089294 (top answer, 5.3k upvotes) · Updated April 2026
> quick_fix
Your local branch has no tracking relationship to a remote branch. Use `git push -u origin <branch-name>` (or just `git push -u origin HEAD`) to push and set the upstream in one command.
# Push and set upstream in one command
git push -u origin HEAD
# Or explicitly name the branch
git push -u origin feature/new-thingWhat causes this error
When you create a local branch with `git checkout -b newbranch`, git does not automatically set an upstream (tracking) relationship to a branch on any remote. On your first push, git refuses because it doesn't know where to push — it needs you to specify the remote (usually `origin`) and, by convention, the same branch name.
How to fix it
- 01
step 1
Run git push with the -u flag
The -u (short for --set-upstream) tells git to remember this remote and branch as the upstream for all future pushes and pulls from this local branch.
git push -u origin HEAD - 02
step 2
For future pushes
Once the upstream is set, you only need `git push` and `git pull` — git remembers the relationship.
- 03
step 3
Optional: make this the default
Run `git config --global push.default current` so every new branch auto-sets its upstream on first push, eliminating this error forever.
git config --global push.default current # With this, `git push` on a new branch just works.
Why no upstream happens at the runtime level
Git stores per-branch config in .git/config under [branch "<name>"] sections with two keys: remote (the named remote like 'origin') and merge (the upstream ref like 'refs/heads/main'). When you run git push without arguments, git looks up these keys for the current branch via git_get_branch_remote and git_get_branch_merge in branch.c. If either is unset, git refuses with 'fatal: The current branch has no upstream branch' from builtin/push.c. The -u flag triggers a write to those config keys after a successful push, binding the local branch to the remote ref permanently.
Common debug mistakes for no upstream
- Running git branch --set-upstream-to=origin/feature without first pushing the branch, the remote ref doesn't exist yet, git refuses, and the user assumes the command is broken.
- Setting push.default = current globally and assuming new branches auto-track, current pushes to a same-named ref but does not write the upstream config, so subsequent git pull still errors.
- Editing .git/config by hand and adding [branch "x"] but spelling 'remote' as 'origin', the section schema requires literal 'remote' and 'merge' keys, not the remote's name.
- Using HEAD in git push -u origin HEAD on a detached HEAD, HEAD doesn't resolve to a branch name, so the upstream is never written and the next push errors again.
- Assuming the error means the remote branch doesn't exist, it can exist already; git is complaining about local config, not remote presence.
When no upstream signals a deeper problem
Frequent encounters with this error across a team signal a branching workflow that creates short-lived branches and never standardised the first-push command. The architectural fix is to set push.autoSetupRemote = true (git 2.37+) globally on every developer machine, which writes the upstream automatically on first push when push.default = current or simple. Combined with a CONTRIBUTING.md note and a shared .gitconfig template, the error class disappears. Without standardisation, every new team member rediscovers the error in their first week and burns time learning git internals when they wanted to ship a feature.
Editor's take
This error has a particular talent for surfacing during CI/CD pipeline setup at the worst possible moment — specifically when a startup's first platform engineer is wiring up GitHub Actions or GitLab CI for the first time and the pipeline runner clones the repo into a shallow detached state, then attempts a push back to a feature branch. The local branch was created interactively on a developer's machine, never pushed, and the CI runner has no upstream reference. The deploy window is 20 minutes before a scheduled maintenance cutover. Nobody on the three-person team has seen this exact error in that context before.
This is solidly a "first three months" error, but the interesting thing is which version of it you encounter. A junior dev hits it on their first feature branch and fixes it by Googling. A mid-level engineer hits it when they've started automating branch creation programmatically — via `git checkout -b` in a script — and realizes the script never called `git push -u`. The insight that separates the two is understanding that `push.autoSetupRemote` (available since Git 2.37.0, released July 2022) can eliminate the entire class of errors, and that `.git/config` is the actual source of truth, not the remote.
In the same incident you'll typically find `fatal: 'origin' does not appear to be a git repository` if the remote URL was misconfigured before the push attempt, or `error: src refspec main does not match any` if the branch was created but never committed to. Downstream, a missing upstream relationship often causes `git pull` to fail with `There is no tracking information for the current branch`, and in GitHub Actions specifically you may see `refusing to allow a GitHub App to create or update workflow files` as a secondary error when the push partially resolves but hits branch protection rules.
By Bikram Nath · Curator · Updated April 2026
Frequently asked questions
Why does git not set the upstream automatically?
Historical default — git wanted you to opt in. Newer versions have push.default=simple which is closer to the behaviour most people want, but you still need -u on the first push.
Can I set the upstream after pushing?
Yes — `git branch --set-upstream-to=origin/mybranch` (no push required if the remote branch already exists).
What is the difference between origin and upstream in git?
'Origin' is the default name for your remote repository (typically your fork or primary remote). 'Upstream' in the context of branch tracking means the remote branch that your local branch is configured to push to and pull from. When git says 'no upstream branch', it means your local branch doesn't know which remote branch to sync with. Set it with `git push -u origin branch-name`.