What causes "issue %s not found" in gastownhall/beads?

Verify the ID with `bd show ` or `bd list`; correct typos in the ID.

issue %s not found

Error message

issue %s not found

What it means

Inside the mutation transaction, workapi.GetIssueOrWisp resolves the issue by ID. If it returns storage.ErrNotFound, the code translates that into a user-facing 'issue <id> not found' error. This is the authoritative existence check before any mutation runs.

Source

Thrown at cmd/bd/mutate_proxied_server.go:25

	"github.com/steveyegge/beads/internal/storage"
	"github.com/steveyegge/beads/internal/storage/uow"
	"github.com/steveyegge/beads/internal/types"
	"github.com/steveyegge/beads/internal/ui"
	"github.com/steveyegge/beads/internal/validation"
	"github.com/steveyegge/beads/internal/workapi"
	"github.com/steveyegge/beads/issueops"
)

func proxiedMutateIssue(ctx context.Context, id, commitMsg string, mutate func(ctx context.Context, uw uow.UnitOfWork, issue *types.Issue, isWisp bool) error) (*types.Issue, error) {
	if uowProvider == nil {
		return nil, fmt.Errorf("proxied-server UOW provider not initialized")
	}
	var updated *types.Issue
	err := uow.RunTx(ctx, uowProvider, func(ctx context.Context, uw uow.UnitOfWork) (string, error) {
		issue, isWisp, rerr := workapi.GetIssueOrWisp(ctx, workapi.NewUOWDetailSource(uw), id)
		if errors.Is(rerr, storage.ErrNotFound) {
			return "", fmt.Errorf("issue %s not found", id)
		}
		if rerr != nil {
			return "", fmt.Errorf("resolving %s: %w", id, rerr)
		}
		if err := validateIssueUpdatable(id, issue); err != nil {
			return "", err
		}
		if err := mutate(ctx, uw, issue, isWisp); err != nil {
			return "", err
		}
		if isWisp {
			updated, _ = uw.IssueUseCase().GetWisp(ctx, issue.ID)
		} else {
			updated, _ = uw.IssueUseCase().GetIssue(ctx, issue.ID)
		}
		return commitMsg, nil
	})
	if err != nil {

View on GitHub (pinned to 71377f2769)

Solutions

Verify the ID with `bd show <id>` or `bd list`; correct typos in the ID.
Run `bd sync`/`bd dolt pull` to pick up deletions/creations from other machines.
Confirm you are in the repo/workspace with the right .beads database.
If the issue should exist, recreate it or restore from history.

Defensive patterns

Strategy: validation

Validate before calling

// Verify the issue exists before mutating
out, err := exec.Command("bd", "show", id, "--json").Output()
if err != nil || len(out) == 0 {
    return fmt.Errorf("skip mutation: %s does not exist locally", id)
}

Try / catch

_, err := proxiedUpdateIssueFields(ctx, id, fields)
if err != nil && strings.Contains(err.Error(), "not found") {
    // treat as absent: correct ID, sync, or skip gracefully
}

Prevention

Copy issue IDs from `bd list`/`bd ready` output instead of typing them
Run `bd sync` before operating across machines
Check `bd show <id>` before scripted bulk updates
Confirm the working directory matches the intended beads database

When it happens

Trigger: Calling any proxied mutation (update fields, `bd note`, etc.) with an issue ID that does not exist in the database (neither as a regular issue nor a wisp).

Common situations: Typo in issue ID (e.g. bd-1234 vs bd-1243); issue deleted on another machine and the deletion synced; operating against a different database (wrong cwd/prefix) than the one containing the issue; wisp already collapsed/purged.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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