gastownhall/beads · error

failed to query orphaned dependencies: %w

Error message

failed to query orphaned dependencies: %w

What it means

OrphanedDependencies in cmd/bd/doctor/fix/validation.go runs a SELECT that unions the dependencies and wisp_dependencies tables and keeps rows whose depends_on_id has no matching issue or wisp. When db.Query itself fails (connection drop, missing table, SQL syntax/permission problem), the function wraps the driver error with this message and aborts the fix. It is a pre-fix data-gathering failure, not a data corruption report.

Source

Thrown at cmd/bd/doctor/fix/validation.go:53

	}
	defer db.Close()

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

	// Find orphaned dependencies (exclude external: cross-rig tracking refs, #1593)
	//nolint:gosec // G202: fixDependencyUnionSQL returns a fixed internal SELECT fragment.
	query := `
		SELECT d.dep_table, d.issue_id, d.depends_on_id
		FROM (` + fixDependencyUnionSQL() + `) d
		WHERE NOT EXISTS (SELECT 1 FROM issues i WHERE i.id = d.depends_on_id)
		  AND NOT EXISTS (SELECT 1 FROM wisps w WHERE w.id = d.depends_on_id)
		  AND d.depends_on_id NOT LIKE 'external:%'
	`
	rows, err := db.Query(query)
	if err != nil {
		return fmt.Errorf("failed to query orphaned dependencies: %w", err)
	}
	defer rows.Close()

	type orphan struct {
		depTable    string
		issueID     string
		dependsOnID string
	}
	var orphans []orphan

	for rows.Next() {
		var o orphan
		if err := rows.Scan(&o.depTable, &o.issueID, &o.dependsOnID); err == nil {
			orphans = append(orphans, o)
		}
	}
	if err := rows.Err(); err != nil {
		return fmt.Errorf("row iteration error: %w", err)

View on GitHub (pinned to 71377f2769)

Solutions

1. Check that the Dolt server (or embedded database) backing the workspace is up and reachable; retry `bd doctor --fix`.
2. Verify the tables exist: run `bd dolt sql -q "SHOW TABLES"` and confirm `dependencies` and `wisp_dependencies` are present; restore or recreate the database if not.
3. Inspect the wrapped driver error (%w) for the root cause (timeout vs. missing table vs. permission) and address that specific condition.
4. If corruption is suspected, back up .beads/ and re-init or restore from a Dolt branch/backup before running fixes again.

Example fix

// before: fix aborts on transient connection drop
rows, err := db.Query(query)
if err != nil {
	return fmt.Errorf("failed to query orphaned dependencies: %w", err)
}
// after: ensure server running / tables present, then retry
// dolt server &  # or: bd dolt sql -q "SHOW TABLES" to confirm schema
rows, err := db.Query(query)
if err != nil {
	return fmt.Errorf("failed to query orphaned dependencies: %w", err) // now succeeds
}

// before invoking the fix, confirm the database is queryable
rows, err := db.Query("SELECT 1 FROM dependencies LIMIT 1")
if err != nil {
	return fmt.Fprintf(os.Stderr, "database not ready: %v\n", err)
}
rows.Close()

var target interface{ Error() string } = err
var sqlErr *driver.Error
if errors.As(target, &sqlErr) {
	// driver-level failure (connection/table) rather than fix-specific problem
}

if err := fix.OrphanedDependencies(path, verbose); err != nil {
	if errors.Is(err, driver.ErrBadConn) || strings.Contains(err.Error(), "connection refused") {
		// restart dolt server, then retry once
	} else {
		log.Fatalf("orphan fix aborted: %v", err)
	}
}

When it happens

Trigger: db.Query returns an error on the orphan-detection SELECT at validation.go:51 — e.g. the Dolt/MySQL connection dropped between openDoltDB and the query, a dependency table is missing or locked, or the query was rejected (syntax/permission/timeout).

Common situations: Dolt server restarted or killed mid-run; database files missing/corrupt so `dependencies` or `wisp_dependencies` tables don't exist; connection to a remote Dolt server times out; wrong working beadsDir so the query hits a partial/empty database; SQL-layer permission errors after a Dolt upgrade.

Understand the failure class

Background: "query failed", "%w: SQL error" — wrapped database query errors in Go libraries explained — this error's family across 3 libraries.

Related errors

• failed to query child-parent dependencies: %w
• failed to begin transaction: %w
• failed to recompute is_blocked: %w
• failed to commit is_blocked repairs: %w
• row iteration error: %w

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