cli/cli · error

resolving --blocking reference %q: %w

Error message

resolving --blocking reference %q: %w

What it means

Thrown by gh issue create when ResolveIssueRef fails for one of the --blocking references. Identical mechanics to --blocked-by: each ref must resolve to an existing issue ID in the mutation payload; the first unresolvable ref aborts the whole create.

Source

Thrown at pkg/cmd/issue/create/create.go:477

		parentID, err := issueShared.ResolveIssueRef(client, baseRepo, opts.Parent)
		if err != nil {
			return api.DeferredUpdateIssueOptions{}, fmt.Errorf("resolving --parent reference %q: %w", opts.Parent, err)
		}
		updateOpts.ParentID = parentID
	}

	for _, ref := range opts.BlockedBy {
		id, err := issueShared.ResolveIssueRef(client, baseRepo, ref)
		if err != nil {
			return api.DeferredUpdateIssueOptions{}, fmt.Errorf("resolving --blocked-by reference %q: %w", ref, err)
		}
		updateOpts.AddBlockedByIDs = append(updateOpts.AddBlockedByIDs, id)
	}

	for _, ref := range opts.Blocking {
		id, err := issueShared.ResolveIssueRef(client, baseRepo, ref)
		if err != nil {
			return api.DeferredUpdateIssueOptions{}, fmt.Errorf("resolving --blocking reference %q: %w", ref, err)
		}
		updateOpts.AddBlockingIDs = append(updateOpts.AddBlockingIDs, id)
	}

	return updateOpts, nil
}

View on GitHub (pinned to 0eeec0b92e)

Solutions

1. Validate each number beforehand with `gh issue view OWNER/REPO#<n>`.
2. Qualify cross-repo refs as OWNER/REPO#n.
3. Create first without --blocking, then add links via `gh issue edit` after verifying numbers.

Example fix

# before
gh issue create --title "x" --blocking 55
# gh: resolving --blocking reference "55": ...

# after
gh issue view owner/repo#55   # exists and is an issue
gh issue create --title "x" --blocking owner/repo#55

for _, ref := range opts.Blocking {
	if _, err := issueShared.ResolveIssueRef(client, baseRepo, ref); err != nil {
		return fmt.Errorf("pre-check failed for %q: %w", ref, err)
	}
}

func isBlockingRefErr(err error) bool {
	return err != nil && strings.Contains(err.Error(), "resolving --blocking reference")
}

if err := createRun(opts); err != nil {
	if isBlockingRefErr(err) {
		// extract the quoted ref, confirm with gh issue view, correct, retry
	}
}

When it happens

Trigger: `gh issue create --blocking 55` where #55 does not exist, is a PR, or belongs to another repo referenced without the OWNER/REPO#n form.

Common situations: Mirrors 833: stale numbers in automation, cross-repo planning, refs copied from a different tracker export.

Related errors

• resolving --parent reference %q: %w
• resolving --blocked-by reference %q: %w
• title can't be blank
• type %q not found; available types: %s
• template %q not found

AI-assisted analysis of cli/cli@0eeec0b92e (2026-08-15). Data as JSON: /api/errors/8d4cf544f67ef9bb. Report an issue: GitHub.