gastownhall/beads · error

iter dependents: scan: %w

Error message

iter dependents: scan: %w

What it means

The dependents iterator failed while scanning a row from the underlying SQL result set into (issue, dependencyType) via scanIssueWithDepTypeFrom. This wraps the driver/scan error so callers of Next() see it with context when they later read it.Err(). It indicates row shape mismatch or a database-level failure mid-iteration.

Source

Thrown at internal/storage/dolt/iter_dependents.go:118

	}
	return &doltDependentsIter{s: s, conn: conn, rows: rows}, nil
}

func (it *doltDependentsIter) Next(ctx context.Context) bool {
	if it.err != nil || it.closed {
		return false
	}
	if err := ctx.Err(); err != nil {
		it.err = err
		return false
	}
	if !it.rows.Next() {
		it.err = it.rows.Err()
		return false
	}
	iss, depType, err := scanIssueWithDepTypeFrom(it.rows)
	if err != nil {
		it.err = fmt.Errorf("iter dependents: scan: %w", err)
		return false
	}
	// NOTE: labels are NOT hydrated here. The corresponding slice path
	// (GetDependentsWithMetadata in dolt/dependencies.go) does not hydrate
	// either, so this matches for parity. Callers that need labels on
	// dependents must call GetLabels(id) explicitly.
	it.cur = &types.IssueWithDependencyMetadata{
		Issue:          *iss,
		DependencyType: types.DependencyType(depType),
	}
	return true
}

func (it *doltDependentsIter) Value() *types.IssueWithDependencyMetadata { return it.cur }
func (it *doltDependentsIter) Err() error                                { return it.err }

func (it *doltDependentsIter) Close() error {
	if it.closed {

View on GitHub (pinned to 71377f2769)

Solutions

1. Check it.Err() after iteration ends to see the wrapped underlying scan error
2. Verify the database schema matches the version of beads you are running (bd doctor / migration steps)
3. Re-open the store / retry the query to rule out a transient connection failure
4. If corruption is suspected, restore from git-backed export (.beads/issues.jsonl) or a Dolt backup

Example fix

// before: ignoring iterator error
for it.Next() { ... }

// after: check iterator error
for it.Next() { ... }
if err := it.Err(); err != nil {
    return fmt.Errorf("iterating dependents: %w", err)
}

// No pre-call validation possible; ensure store is open and schema current.
if store == nil { return errors.New("store not initialized") }

for it.Next() {
    // process
}
if err := it.Err(); err != nil {
    if strings.Contains(err.Error(), "iter dependents: scan") {
        // handle scan/schema failure: log, run migrations, or abort
    }
}

When it happens

Trigger: Calling DoltStore.Next() on the iterator returned by iteration over dependents when a result row cannot be scanned: NULL in a NOT-NULL-mapped column, unexpected column count/type after a schema change, or driver read error.

Common situations: Schema drift between the beads binary and an older/newer .beads Dolt database; manual schema edits; corrupted database rows; connection dropped mid-scan.

Related errors

• iter issues: scan: %w
• scan config conflict: %w
• ErrExec
• database not available: %w
• not using Dolt backend (configured backend %q)

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