gastownhall/beads · error

--merged-into value %q does not name an existing unambiguous

Error message

--merged-into value %q does not name an existing unambiguous ref

What it means

When resolving a `--merged-into` selector into a pinned worktree comparator, bd first tries to match it against candidate refs. If exactly one match exists the ref is pinned; if no (or multiple) matches exist and the selector is not already a full-length hex object ID, this error is thrown because the selector does not name one existing, unambiguous ref.

Source

Thrown at cmd/bd/worktree_cmd.go:1737

	}
	hashLength, err := repositoryObjectIDLength(ctx, git, executionRoot)
	if err != nil {
		return pinnedWorktreeComparator{}, err
	}
	fullOID := isHexObjectID(selector, hashLength)

	if len(matches) > 1 || fullOID && len(matches) > 0 {
		return pinnedWorktreeComparator{}, fmt.Errorf(
			"--merged-into value %q is ambiguous; use a full ref name or a non-ref full object ID (matches: %s)",
			selector,
			strings.Join(matches, ", "),
		)
	}
	if len(matches) == 1 {
		return pinWorktreeComparatorRef(ctx, git, executionRoot, target, selector, matches[0], true)
	}
	if !fullOID {
		return pinnedWorktreeComparator{}, fmt.Errorf(
			"--merged-into value %q does not name an existing unambiguous ref",
			selector,
		)
	}

	oid, err := resolveWorktreeCommitOID(ctx, git, executionRoot, selector)
	if err != nil {
		return pinnedWorktreeComparator{}, fmt.Errorf(
			"--merged-into object ID %q does not resolve to a commit: %w",
			selector,
			err,
		)
	}
	if oid == target.headOID {
		return pinnedWorktreeComparator{}, fmt.Errorf(
			"--merged-into object ID %q is the target HEAD itself; use a ref or descendant commit that independently proves containment",
			selector,
		)

View on GitHub (pinned to 71377f2769)

Solutions

1. Use the fully qualified ref name, e.g. `refs/heads/main` or `origin/main`, so the match is unambiguous
2. Run `git for-each-ref` and confirm exactly one ref corresponds to your selector
3. Pass the full 40/64-character commit OID instead of a ref name
4. Check for typos and confirm the branch still exists in the repository

Example fix

// before
bd worktree remove --merged-into feature-x
// after
bd worktree remove --merged-into refs/heads/feature-x

// shell pre-check: exactly one ref matches
count=$(git for-each-ref --format='%(refname)' -- "refs/heads/${SEL}" "refs/remotes/${SEL}" | wc -l)
[ "$count" -eq 1 ] || echo "ambiguous or missing: $SEL"

When it happens

Trigger: Passing `bd worktree remove --merged-into <selector>` where the selector matches zero candidate refs (typo, deleted branch) or matches more than one ref (e.g. `origin/foo` and `refs/heads/foo`), and the selector is not a full OID.

Common situations: Typos in branch names; ambiguous short names matching both a local and a remote-tracking ref; the merged-into branch was deleted after the merge; using a partial/abbreviated OID shorter than the full hash.

Related errors

• worktree name %q is ambiguous; use an absolute path (matches
• comparison ref %q does not resolve to a commit: %w
• ErrAmbiguousID
• auto-export: git add failed: %w
• failed to read .gitignore: %w

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