gastownhall/beads · error

failed to scan dependency keys: %w

Error message

failed to scan dependency keys: %w

What it means

repairDependencyKeys first calls ScanDependencyKeys to find mis-keyed or null-target dependency rows; if that scan returns any error (connection failure, rows iteration error, table-existence check failure), it is wrapped as "failed to scan dependency keys: %w". This is the top-level signal that the repair aborted before making any changes — nothing was written.

Source

Thrown at cmd/bd/doctor/fix/dep_keys.go:105

		fmt.Printf("  Dependency key fix skipped (%v)\n", err)
		return nil
	}
	defer db.Close()

	if skip, err := guardFixTarget("Dependency key fix", db, beadsDir, cfg); skip {
		return err
	}

	return repairDependencyKeys(context.Background(), db, verbose)
}

// repairDependencyKeys scans and repairs rekey-backfill leftovers on an open
// connection. Split from DependencyKeys so the repair logic is testable
// against an existing store handle.
func repairDependencyKeys(ctx context.Context, db *sql.DB, verbose bool) error {
	anomalies, err := ScanDependencyKeys(ctx, db)
	if err != nil {
		return fmt.Errorf("failed to scan dependency keys: %w", err)
	}
	if len(anomalies) == 0 {
		fmt.Println("  No dependency key anomalies to fix")
		return nil
	}

	// Uses explicit transaction so writes persist when @@autocommit is OFF
	// (e.g. Dolt server started with --no-auto-commit).
	tx, err := db.Begin()
	if err != nil {
		return fmt.Errorf("failed to begin transaction: %w", err)
	}
	var rekeyed, removed, failed int
	repairedTables := make(map[string]bool)
	for _, a := range anomalies {
		showIndividual := verbose || len(a.MisKeyed)+len(a.NullTarget) < 20
		for _, mk := range a.MisKeyed {
			//nolint:gosec // G201: table is a hardcoded constant, never user input.

View on GitHub (pinned to 71377f2769)

Solutions

1. Verify the database is reachable (start/restart the Dolt server, check bd doctor database status)
2. Re-run the fix command once the connection is stable
3. If a specific table is failing, inspect that table's health directly and repair or restore it

Example fix

// before (broken connection)
err := repairDependencyKeys(ctx, db, verbose) // "failed to scan dependency keys: ..."
// after (caller guards)
if err := db.PingContext(ctx); err != nil {
	return fmt.Errorf("database unreachable: %w", err)
}
return repairDependencyKeys(ctx, db, verbose)

if err := db.PingContext(ctx); err != nil {
	return fmt.Errorf("skipping dependency key repair, DB unreachable: %w", err)
}

if err := repairDependencyKeys(ctx, db, verbose); err != nil {
	if strings.HasPrefix(err.Error(), "failed to scan dependency keys") {
		log.Printf("repair aborted before any writes (safe to retry): %v", err)
		return err
	}
	return err
}

When it happens

Trigger: Running `bd doctor` dependency-keys fix (or the test) when ScanDependencyKeys returns an error: e.g. the dependency tables cannot be queried because the DB connection is down, a table query fails, or the rows cursor errors (see error 410).

Common situations: Dolt server not running or restarting during `bd doctor fix`; database migration incomplete so dependency tables are unreadable; permission errors on the database user.

Related errors

• ErrScan
• failed to load config: %w
• failed to commit is_blocked repairs to Dolt: %w
• failed to begin transaction: %w
• failed to commit dependency key repairs: %w

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