What causes "failed to verify eligibility: %w" in gastownhall/beads?

Inspect the wrapped error for the storage-layer root cause

failed to verify eligibility: %w

Error message

failed to verify eligibility: %w

What it means

CompactTier1 first asks the store whether the issue can be compacted via CheckEligibility. If that store call itself returns an error (not an 'ineligible' verdict), the compaction is aborted with this wrapped error. It signals a storage/backend failure, not a policy rejection.

Source

Thrown at internal/compact/compactor.go:96

	}

	return &Compactor{
		store:      store,
		summarizer: haiClient,
		config:     config,
	}, nil
}

// CompactTier1 compacts a single issue at Tier 1 (basic summarization).
func (c *Compactor) CompactTier1(ctx context.Context, issueID string) error {
	if ctx.Err() != nil {
		return ctx.Err()
	}

	// Check eligibility before fetching issue (fail fast)
	eligible, reason, err := c.store.CheckEligibility(ctx, issueID, 1)
	if err != nil {
		return fmt.Errorf("failed to verify eligibility: %w", err)
	}
	if !eligible {
		if reason != "" {
			return fmt.Errorf("issue %s is not eligible for Tier 1 compaction: %s", issueID, reason)
		}
		return fmt.Errorf("issue %s is not eligible for Tier 1 compaction", issueID)
	}

	issue, err := c.store.GetIssue(ctx, issueID)
	if err != nil {
		return fmt.Errorf("failed to fetch issue: %w", err)
	}

	// Calculate original size
	originalSize := len(issue.Description) + len(issue.Design) + len(issue.Notes) + len(issue.AcceptanceCriteria)

	if c.config.DryRun {
		return fmt.Errorf("dry-run: would compact %s (original size: %d bytes)", issueID, originalSize)

View on GitHub (pinned to 71377f2769)

Solutions

Inspect the wrapped error for the storage-layer root cause
Verify the database exists and is reachable (bd doctor / check .beads directory)
Retry after the database/connection recovers
Check the context passed in has not already timed out

Example fix

// before
if err := c.CompactTier1(ctx, id); err != nil { log.Fatal(err) }
// after
if err := ctx.Err(); err != nil { return err }
if err := c.CompactTier1(ctx, id); err != nil {
    if errors.Is(err, sql.ErrConnDone) || ctx.Err() != nil { /* retry or abort cleanly */ }
    return err
}

Defensive patterns

Strategy: retry

Validate before calling

if err := ctx.Err(); err != nil { return err }
if _, err := os.Stat(".beads"); err != nil { return fmt.Errorf("database not initialized") }

Try / catch

err := c.CompactTier1(ctx, id)
if err != nil && strings.Contains(err.Error(), "failed to verify eligibility") {
    // storage-layer issue: retry after backoff
    time.Sleep(time.Second)
    err = c.CompactTier1(ctx, id)
}
return err

Prevention

Run `bd doctor` before batch compaction to verify database health
Ensure the database is initialized and reachable before compacting
Use a context with a sane deadline, not one already near expiry
Retry eligibility errors with backoff — they are usually transient storage faults

When it happens

Trigger: store.CheckEligibility(ctx, issueID, 1) returns a non-nil error — e.g. database connection failure, the issues table is missing, the issue ID lookup itself errored at the storage layer, or the context is cancelled mid-query.

Common situations: Dolt/SQLite database not initialized or corrupted; running `bd compact` before `bd init`; network/database outage; context deadline exceeded during the eligibility query.

Related errors

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