gastownhall/beads · error

iter issues: scan: %w

Error message

iter issues: scan: %w

What it means

IterIssues failed while scanning one row of the issues SELECT into a types.Issue via issueops.ScanIssueFrom. Materialization stops immediately and the read transaction is rolled back; no iterator is returned to the caller.

Source

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

		limitSQL = fmt.Sprintf(" LIMIT %d", filter.Limit)
	}

	//nolint:gosec // G201: whereSQL contains column comparisons with ?, limitSQL is a safe integer
	q := fmt.Sprintf(`SELECT %s FROM issues %s %s ORDER BY priority ASC, created_at DESC, id ASC%s`,
		issueops.IssueSelectColumns, sqlbuild.LeaseJoin("issues"), whereSQL, limitSQL)

	var issues []*types.Issue
	txErr := s.withReadTx(ctx, func(tx *sql.Tx) error {
		rows, err := tx.QueryContext(ctx, q, args...)
		if err != nil {
			return fmt.Errorf("iter issues: query: %w", err)
		}
		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
			}

View on GitHub (pinned to 71377f2769)

Solutions

1. Check the wrapped error to find which column failed to scan
2. Run migrations / bd doctor to fix schema-version mismatch
3. Identify and repair or export-rebuild the offending row(s)
4. Upgrade or downgrade beads so the scanner matches the on-disk schema

// Verify schema version compatibility before scanning large result sets
// (run bd doctor or equivalent schema check at startup)

iter, err := store.IterIssues(ctx, query, filter)
if err != nil && strings.Contains(err.Error(), "scan:") {
    // schema/data mismatch: surface for migration or repair
    return fmt.Errorf("database schema may be outdated: %w", err)
}

When it happens

Trigger: A row whose columns don't match ScanIssueFrom expectations: NULL in a non-nullable target, wrong column ordering after IssueSelectColumns/schema mismatch, or value conversion failure (e.g. malformed timestamp).

Common situations: Schema drift between binary and database version; rows written by a different beads version; manual edits to the issues table; corrupted row data in Dolt.

Related errors

• iter dependents: scan: %w
• scan config conflict: %w
• scan remote: %w
• ErrExec
• database not available: %w

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