upstream branch %s/%s not found. If you expect it to exist,

Error message

upstream branch %s/%s not found.
If you expect it to exist, you should fetch (with 'f').
Otherwise, you should push (with 'shift+P')

What it means

SyncController.setCurrentBranchUpstream (pkg/gui/controllers/sync_controller.go) runs git branch --set-upstream-to=<remote>/<branch>; if git fails with an error containing 'does not exist' it rewrites it into this actionable hint: the upstream ref is unknown locally, so either fetch it ('f') or push the branch ('shift+P') to create it on the remote first.

Source

Thrown at pkg/gui/controllers/sync_controller.go:143

				return err
			}

			return self.PullAux(currentBranch, PullFilesOptions{Action: action})
		})
	}

	return self.PullAux(currentBranch, PullFilesOptions{Action: action})
}

func (self *SyncController) setCurrentBranchUpstream(upstream string) error {
	upstreamRemote, upstreamBranch, err := self.c.Helpers().Upstream.ParseUpstream(upstream)
	if err != nil {
		return err
	}

	if err := self.c.Git().Branch.SetCurrentBranchUpstream(upstreamRemote, upstreamBranch); err != nil {
		if strings.Contains(err.Error(), "does not exist") {
			return fmt.Errorf(
				"upstream branch %s/%s not found.\nIf you expect it to exist, you should fetch (with 'f').\nOtherwise, you should push (with 'shift+P')",
				upstreamRemote, upstreamBranch,
			)
		}
		return err
	}
	return nil
}

type PullFilesOptions struct {
	UpstreamRemote  string
	UpstreamBranch  string
	FastForwardOnly bool
	Action          string
}

func (self *SyncController) PullAux(currentBranch *models.Branch, opts PullFilesOptions) error {
	return self.c.WithInlineStatus(currentBranch, types.ItemOperationPulling, context.LOCAL_BRANCHES_CONTEXT_KEY, func(task gocui.Task) error {

View on GitHub (pinned to c477a2959b)

Solutions

Press 'f' (fetch) to pull refs from the remote, then set the upstream again.
If the branch does not exist on the remote yet, push it first ('shift+P' pushes with upstream, or use the push-and-set-upstream option).
Double-check the remote/branch spelling in the upstream prompt before confirming.

Example fix

# terminal equivalent
# before (fails): upstream not known locally
git branch --set-upstream-to=origin/feature-x feature-x

# after
git fetch origin
git branch --set-upstream-to=origin/feature-x feature-x
# or, if never pushed:
git push -u origin feature-x

Defensive patterns

Strategy: retry

Try / catch

if err := set_upstream_to("origin/feature-x"); err != nil {
	if strings.Contains(err.Error(), "not found") {
		_ = fetch("origin")            // then retry once
		err = set_upstream_to("origin/feature-x")
	}
	if err != nil {
		_ = push_with_upstream()        // branch never pushed: push -u creates it
	}
}

Prevention

Push new branches with `git push -u` (lazygit: 'shift+P' / upstream options) so tracking refs exist.
Fetch after cloning or when teammates create branches you want to track.
Confirm remote/branch spelling in the upstream prompt before accepting.

When it happens

Trigger: Setting an upstream for a branch (e.g. via the upstream-options menu) whose remote-tracking ref refs/remotes/<remote>/<branch> does not exist locally — because the branch was never pushed, or the remote has it but it was never fetched.

Common situations: New local branches before first push; after cloning a repo whose remote gained new branches that were never fetched; working offline so the fetch fails silently; upstream names with typos so the ref genuinely does not exist.

Related errors

AI-assisted analysis of jesseduffield/lazygit@c477a2959b (2026-08-15). Data as JSON: /api/errors/89be9f8966e1c088. Report an issue: GitHub.