gastownhall/beads · error

iter issues: hydrate labels: %w

Error message

iter issues: hydrate labels: %w

What it means

IterIssues batches label hydration after the main scan: GetLabelsForIssuesFromTableInTx runs on the same transaction (after the cursor is closed, since *sql.Tx is single-connection). If that labels query fails, all fetched issues are discarded and this wrapped error is returned.

Source

Thrown at internal/storage/dolt/iter_issues.go:84

		defer func() { _ = rows.Close() }()
		ids := make([]string, 0)
		for rows.Next() {
			iss, scanErr := issueops.ScanIssueFrom(rows)
			if scanErr != nil {
				return fmt.Errorf("iter issues: scan: %w", scanErr)
			}
			issues = append(issues, iss)
			ids = append(ids, iss.ID)
		}
		if err := rows.Err(); err != nil {
			return fmt.Errorf("iter issues: rows: %w", err)
		}
		// A *sql.Tx is bound to one connection, so the cursor must be closed
		// before the label query can run on it (idempotent with the defer).
		_ = rows.Close()
		labelMap, err := issueops.GetLabelsForIssuesFromTableInTx(ctx, tx, "labels", ids)
		if err != nil {
			return fmt.Errorf("iter issues: hydrate labels: %w", err)
		}
		for _, iss := range issues {
			if labels, ok := labelMap[iss.ID]; ok {
				iss.Labels = labels
			}
		}
		return nil
	})
	if txErr != nil {
		return nil, txErr
	}
	return storage.NewSliceIter(issues), nil
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Check the wrapped error (missing table vs unknown column vs connection error)
2. Run migrations / bd doctor to ensure the labels table exists with the expected schema
3. Retry on transient failures — the whole IterIssues call is retried atomically
4. If upgrading from a pre-labels database, follow the documented migration path

iter, err := store.IterIssues(ctx, query, filter)
if err != nil && strings.Contains(err.Error(), "hydrate labels") {
    // labels table issue: retry once, then check schema
    return retryOrMigrate(err)
}

When it happens

Trigger: Calling IterIssues when the labels table is missing, renamed, or its schema differs from what GetLabelsForIssuesFromTableInTx expects, or the tx connection fails during the label query.

Common situations: Databases created before the labels table existed (old versions); manual schema changes; corruption in the labels table; transient connection failure between the two queries.

Related errors

• read labels for %s: %w
• copy label %q for %s: %w
• hydrate issue labels: %w
• ErrExec
• database not available: %w

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