gastownhall/beads · error

list branches: %w

Error message

list branches: %w

What it means

ListBranches queries `SELECT name FROM dolt_branches ORDER BY name` and wraps query failure as "list branches: <cause>". It throws when the query cannot be executed — the dolt_branches system table is unavailable, the connection is broken, or the target is not a Dolt database. This is the first step of the function, so no partial data is returned.

Source

Thrown at internal/storage/versioncontrolops/branches.go:12

package versioncontrolops

import (
	"context"
	"fmt"
)

// ListBranches returns the names of all Dolt branches, sorted by name.
func ListBranches(ctx context.Context, db DBConn) ([]string, error) {
	rows, err := db.QueryContext(ctx, "SELECT name FROM dolt_branches ORDER BY name")
	if err != nil {
		return nil, fmt.Errorf("list branches: %w", err)
	}
	defer rows.Close()

	var branches []string
	for rows.Next() {
		var name string
		if err := rows.Scan(&name); err != nil {
			return nil, fmt.Errorf("scan branch: %w", err)
		}
		branches = append(branches, name)
	}
	return branches, rows.Err()
}

// CurrentBranch returns the name of the active branch.
func CurrentBranch(ctx context.Context, db DBConn) (string, error) {
	var branch string
	if err := db.QueryRowContext(ctx, "SELECT active_branch()").Scan(&branch); err != nil {

View on GitHub (pinned to 71377f2769)

Solutions

1. Confirm the connection targets a Dolt database with dolt_branches available (SELECT 1 FROM dolt_branches LIMIT 1)
2. Ensure a database is in use (USE db / connection DSN dbname) before listing
3. Inspect the wrapped cause to separate connectivity from schema issues
4. Retry transient connection errors

Example fix

// before
branches, err := vcops.ListBranches(ctx, db)
// after
if err := db.PingContext(ctx); err != nil { return fmt.Errorf("db down: %w", err) }
branches, err := vcops.ListBranches(ctx, db)
if err != nil { return fmt.Errorf("branches: %w", err) }

var one int
if err := db.QueryRowContext(ctx, "SELECT 1 FROM dolt_branches LIMIT 1").Scan(&one); err != nil {
	return fmt.Errorf("not a dolt database: %w", err)
}

branches, err := vcops.ListBranches(ctx, db)
if err != nil {
	if strings.Contains(err.Error(), "list branches") && errors.Is(errors.Unwrap(err), sql.ErrConnDone) {
		return reconnectAndRetry()
	}
	return err
}

When it happens

Trigger: ListBranches(ctx, db) when db.QueryContext fails: connection error, database not a Dolt DB (no dolt_branches table), wrong database selected, or server version lacking the table.

Common situations: Pointing the connection at a non-Dolt MySQL database; calling before selecting/creating a database on the server; network drop; Dolt version too old for dolt_branches.

Related errors

• failed to query dolt_status: %w
• descendants: query: %w
• db: ListRemotes: query: %w
• query dependency conflicts: %w
• get status: %w

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