gastownhall/beads · error

list remote-tracking refs: %w

Error message

list remote-tracking refs: %w

What it means

ListRemoteRefs queries the dolt_remote_branches system table to enumerate cached remote-tracking refs (e.g. "remotes/origin/main"). This error wraps any failure of the initial QueryContext — typically a SQL error from the underlying Dolt database (missing system table, connection failure, server error, or cancelled context). It is thrown so callers can distinguish the listing step from later scan/delete failures.

Source

Thrown at internal/storage/versioncontrolops/remoterefs.go:13

package versioncontrolops

import (
	"context"
	"fmt"
)

// ListRemoteRefs returns the names of all cached remote-tracking refs
// (e.g. "remotes/origin/main"), sorted by name.
func ListRemoteRefs(ctx context.Context, db DBConn) ([]string, error) {
	rows, err := db.QueryContext(ctx, "SELECT name FROM dolt_remote_branches ORDER BY name")
	if err != nil {
		return nil, fmt.Errorf("list remote-tracking refs: %w", err)
	}
	defer rows.Close()

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

// PruneRemoteRefs deletes every cached remote-tracking ref and returns the
// names deleted. After a history squash (Flatten/Compact) these refs still
// anchor the pre-squash commit chain, so DOLT_GC treats the entire old history
// as reachable and reclaims nothing (bd-agctw). Pruning is safe on a squashed

View on GitHub (pinned to 71377f2769)

Solutions

1. Check the wrapped error (%w) for the underlying cause: connection errors require reconnecting to the Dolt database before retrying.
2. If the context was cancelled/timed out, retry with a fresh, longer-lived context.
3. Verify the Dolt engine version supports dolt_remote_branches; upgrade the Dolt driver/server if the system table is missing.
4. Confirm the DBConn passed in is open and healthy (ping the database first).

Example fix

// before
refs, err := versioncontrolops.ListRemoteRefs(ctx, brokenConn)
// after
if err := db.PingContext(ctx); err != nil {
    db, err = sql.Open("mysql", dsn) // re-open stale connection
}
refs, err := versioncontrolops.ListRemoteRefs(ctx, db)

if err := db.PingContext(ctx); err != nil {
    return fmt.Errorf("database unavailable before ListRemoteRefs: %w", err)
}

func isCtxCancelled(err error) bool {
    return errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded)
}

refs, err := versioncontrolops.ListRemoteRefs(ctx, db)
if err != nil {
    switch {
    case errors.Is(err, context.Canceled), errors.Is(err, context.DeadlineExceeded):
        // retry with fresh context
    default:
        return fmt.Errorf("listing remote refs failed: %w", err)
    }
}

When it happens

Trigger: Calling ListRemoteRefs (directly or via PruneRemoteRefs) when db.QueryContext(ctx, "SELECT name FROM dolt_remote_branches ORDER BY name") fails: the connection is closed/broken, the Dolt server rejects the query, dolt_remote_branches is unavailable (very old Dolt version), or ctx is cancelled before the query starts.

Common situations: Database connection dropped mid-session; running against an embedded Dolt version that predates dolt_remote_branches; caller passed a context that was already cancelled or timed out; permissions/config issues preventing system-table reads.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 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/17bdc49ef226d69c. Report an issue: GitHub.