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

Verify the issue ID with 'bd show ' and correct the typo

issue %s not found

Error message

issue %s not found

What it means

Exists() is an IssueValidator that rejects a nil issue. The database lookup for the given issue ID returned no row, so validation fails with 'issue <id> not found' before the operation proceeds.

Source

Thrown at internal/validation/issue.go:32

// Chain composes multiple validators into a single validator.
// Validators are executed in order and the first error stops the chain.
func Chain(validators ...IssueValidator) IssueValidator {
	return func(id string, issue *types.Issue) error {
		for _, v := range validators {
			if err := v(id, issue); err != nil {
				return err
			}
		}
		return nil
	}
}

// Exists validates that an issue is not nil.
func Exists() IssueValidator {
	return func(id string, issue *types.Issue) error {
		if issue == nil {
			return fmt.Errorf("issue %s not found", id)
		}
		return nil
	}
}

// NotTemplate validates that an issue is not a template.
// Templates are read-only and cannot be modified.
func NotTemplate() IssueValidator {
	return func(id string, issue *types.Issue) error {
		if issue == nil {
			return nil // Let Exists() handle nil check if needed
		}
		if issue.IsTemplate {
			return fmt.Errorf("cannot modify template %s: templates are read-only; use 'bd mol pour' to create a work item", id)
		}
		return nil
	}
}

View on GitHub (pinned to 71377f2769)

Solutions

Verify the issue ID with 'bd show <id>' and correct the typo
Run 'bd list' to find the correct issue ID
Check you are operating in the repository/database that owns the issue (check .beads directory)
If the issue was deleted, recreate it with 'bd create'

Example fix

// before
bd close bd-42x  // typo'd ID
// after
bd list | grep 42  # find correct ID, then
bd close bd-42

Defensive patterns

Strategy: validation

Validate before calling

issue, err := store.GetIssue(ctx, id)
if err != nil || issue == nil {
    return fmt.Errorf("issue %s does not exist; run 'bd list' to find the correct ID", id)
}

Type guard

func issueExists(issue *types.Issue) bool { return issue != nil }

Try / catch

if err := doOp(id); err != nil {
    if strings.Contains(err.Error(), "not found") {
        // refresh from 'bd list' and retry with corrected ID
    }
    return err
}

Prevention

Copy issue IDs from 'bd list'/'bd show' output rather than typing them
Verify the ID exists before scripting bulk operations
Check you are in the repository whose .beads database owns the issue

When it happens

Trigger: Calling any update/close/assign path that runs validators with an issue ID that does not exist in the database (typo'd ID, deleted/closed-and-purged issue, wrong database/prefix).

Common situations: Typo in a bd issue ID; referencing an issue from another repo's database; issue was deleted by a teammate; stale cached ID after a fresh clone or re-sync.

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/c8baa1c8202f6855. Report an issue: GitHub.