gastownhall/beads · error

failed to get diff: %w

Error message

failed to get diff: %w

What it means

This error wraps a failure executing the dolt_diff() table-function query in DiffInTx. Refs were already validated, so failures come from the database: an unknown ref (branch/commit doesn't exist), a missing issues table, a Dolt engine error, or a connection problem. It means the diff could not start streaming rows at all.

Source

Thrown at internal/storage/issueops/diff.go:38

	if err := ValidateRef(toRef); err != nil {
		return nil, fmt.Errorf("invalid toRef: %w", err)
	}

	query := fmt.Sprintf(`
		SELECT
			COALESCE(from_id, '') as from_id,
			COALESCE(to_id, '') as to_id,
			diff_type,
			from_title, to_title,
			from_description, to_description,
			from_status, to_status,
			from_priority, to_priority
		FROM dolt_diff('%s', '%s', 'issues')
	`, fromRef, toRef)

	rows, err := tx.QueryContext(ctx, query)
	if err != nil {
		return nil, fmt.Errorf("failed to get diff: %w", err)
	}
	defer rows.Close()

	var entries []*storage.DiffEntry
	for rows.Next() {
		var fromID, toID, diffType string
		var fromTitle, toTitle, fromDesc, toDesc, fromStatus, toStatus *string
		var fromPriority, toPriority *int

		if err := rows.Scan(&fromID, &toID, &diffType,
			&fromTitle, &toTitle,
			&fromDesc, &toDesc,
			&fromStatus, &toStatus,
			&fromPriority, &toPriority); err != nil {
			return nil, fmt.Errorf("failed to scan diff: %w", err)
		}

		entry := &storage.DiffEntry{

View on GitHub (pinned to 71377f2769)

Solutions

1. Check the wrapped cause: an 'unknown ref' error means the branch/commit is absent locally — fetch or create it first
2. Verify both refs resolve (e.g. dolt branch / query dolt_log) before diffing
3. Confirm the issues table exists at both refs
4. Ensure you are connected to a Dolt database; dolt_diff is Dolt-specific and unavailable on MySQL/SQLite

Example fix

// before
rows, err := tx.QueryContext(ctx, query)
if err != nil {
    return nil, fmt.Errorf("failed to get diff: %w", err)
}
// after
rows, err := tx.QueryContext(ctx, query)
if err != nil {
    return nil, fmt.Errorf("failed to get diff %s..%s (does the ref exist locally? run fetch first): %w", fromRef, toRef, err)
}

// verify refs and table exist before diffing
for _, ref := range []string{from, to} {
    if err := db.QueryRow("SELECT COUNT(*) FROM dolt_branches WHERE name = ?", ref).Scan(&n); err != nil || n == 0 {
        if !isCommitRef(ref) { // fall back: try resolving as commit hash
            return fmt.Errorf("ref %q not found locally; run fetch first", ref)
        }
    }
}

entries, err := issueops.DiffInTx(ctx, tx, from, to)
if err != nil {
    if strings.Contains(err.Error(), "failed to get diff") && strings.Contains(err.Error(), "unknown ref") {
        // fetch or create the missing ref, then retry once
        return retryAfterFetch(ctx, from, to)
    }
    return err
}

When it happens

Trigger: tx.QueryContext on "SELECT ... FROM dolt_diff('<from>','<to>','issues')" fails: non-existent fromRef/toRef in the local database, issues table absent at those refs, Dolt engine error, or connection failure.

Common situations: Diffing a branch that was never fetched (exists only on the remote); diffing against a bare/non-Dolt database where dolt_diff() doesn't exist; diffing before the issues table was created at the given ref.

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 begin transaction: %w
• failed to recompute is_blocked: %w
• failed to commit is_blocked repairs: %w
• failed to query orphaned dependencies: %w
• row iteration error: %w

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