gastownhall/beads · error

failed to inspect configured upstream: %w

Error message

failed to inspect configured upstream: %w

What it means

This error wraps a failure from `git for-each-ref --format=%(upstream)` used to discover the upstream of the target branch. It also (in the same function) covers the case where the upstream is empty or ambiguous (multiple lines). The library needs exactly one resolvable upstream to compute unpushed commits; if the git query fails or the branch has none, it reports this wrapped error or the follow-up 'no single resolvable upstream' error.

Source

Thrown at cmd/bd/worktree_cmd.go:1980

	git *worktreeRemovalGit,
	executionRoot string,
	target pinnedWorktreeTarget,
) (pinnedWorktreeComparator, error) {
	if target.branch == "" || target.detached {
		return pinnedWorktreeComparator{}, fmt.Errorf(
			"cannot verify unpushed commits: target is detached; use --merged-into <ref>",
		)
	}
	output, err := git.output(
		ctx,
		executionRoot,
		"for-each-ref",
		"--format=%(upstream)",
		"--",
		target.branch,
	)
	if err != nil {
		return pinnedWorktreeComparator{}, fmt.Errorf("failed to inspect configured upstream: %w", err)
	}
	upstreamRef := strings.TrimSpace(string(output))
	if upstreamRef == "" || strings.Contains(upstreamRef, "\n") {
		return pinnedWorktreeComparator{}, fmt.Errorf(
			"cannot verify unpushed commits: the target branch has no single resolvable upstream; configure an upstream or use --merged-into <ref>",
		)
	}
	return pinWorktreeComparatorRef(
		ctx,
		git,
		executionRoot,
		target,
		upstreamRef,
		upstreamRef,
		false,
	)
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Set an upstream for the branch: `git push -u origin <branch>` (or `git branch --set-upstream-to=origin/<branch> <branch>`).
2. Bypass upstream detection by passing --merged-into <ref> with an explicit comparison reference.
3. Inspect `git config branch.<name>.remote` / `git config branch.<name>.merge` and fix the branch configuration if it points at a deleted remote.

Example fix

// before
git push origin feature-x   # upstream not configured -> error
// after
git push -u origin feature-x

upstream, _ := execGit("git", "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}")
if strings.TrimSpace(upstream) == "" {
    // no upstream configured: set one or use --merged-into
    execGit("git", "push", "-u", "origin", branch)
}

out, err := runWorktreeVerify(...)
if err != nil && strings.Contains(err.Error(), "failed to inspect configured upstream") {
    return runWorktreeVerify(..., "--merged-into", "main")
}

When it happens

Trigger: Calling the pinned-worktree comparison flow when (a) the underlying `git for-each-ref` command fails (corrupt repo, bad ref, git not found), or (b) `target.branch` has no configured upstream (`branch.<name>.remote` unset), or the format resolves to multiple/ambiguous upstream entries.

Common situations: Locally created branches never pushed (`git push -u` never run); branches pushed via explicit `git push origin <branch>` without setting upstream; shallow/CI clones with limited ref configuration; renamed branches whose upstream config was lost.

Related errors

• failed to inspect created worktree cleanliness: %w %s
• created worktree is dirty after checkout; refusing to contin
• worktree not found: %s
• failed to read git worktree registry: %w
• git worktree registry is empty

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/8b8ea56876af80d0. Report an issue: GitHub.