What causes "list existing remotes: %w" in gastownhall/beads?

Read the wrapped cause: if the server failed to start, restart it or re-run the command (cold start is retried automatically)

gastownhall/beads · error

list existing remotes: %w

Error message

list existing remotes: %w

What it means

ensureDoltRemote first lists existing Dolt remotes via st.ListRemotes(ctx) to decide whether the requested remote already exists. If listing fails (server unavailable, driver error, permissions), the error is wrapped as 'list existing remotes'. This is the entry point of remote add/push flows and fails before any mutation.

Source

Thrown at cmd/bd/dolt.go:1548

		return false
	}
	response = strings.TrimSpace(strings.ToLower(response))
	return response == "y" || response == "yes"
}

func findDoltRemoteURL(remotes []storage.RemoteInfo, name string) string {
	for _, remote := range remotes {
		if remote.Name == name {
			return remote.URL
		}
	}
	return ""
}

func ensureDoltRemote(ctx context.Context, st doltRemoteAddStore, name, url string, confirm doltRemoteOverwriteConfirmer) (doltRemoteAddResult, error) {
	remotes, err := st.ListRemotes(ctx)
	if err != nil {
		return doltRemoteAddResult{}, fmt.Errorf("list existing remotes: %w", err)
	}

	existingURL := findDoltRemoteURL(remotes, name)
	existingFromDiskOnly := false
	if existingURL == "" {
		// An empty listing is not proof the remote is absent: a freshly
		// (auto-)started sql-server can report empty dolt_remotes while the
		// remote is persisted on disk (GH#2118, wy-6k7f7). Recover the
		// persisted URL so the add gets the same match/confirm treatment it
		// would after the window, instead of silently writing over an
		// invisible remote.
		existingURL = findDoltRemoteURL(persistedRemoteInfosFor(st), name)
		existingFromDiskOnly = existingURL != ""
	}
	if existingURL == "" {
		if err := st.AddRemote(ctx, name, url); err != nil {
			return doltRemoteAddResult{}, fmt.Errorf("add remote %s: %w", name, err)
		}

View on GitHub (pinned to 71377f2769)

Solutions

Read the wrapped cause: if the server failed to start, restart it or re-run the command (cold start is retried automatically)
Check .beads dolt storage integrity; consult `bd doctor` for database issues
Retry after resolving any driver/permission error reported underneath
If the DB is corrupted, restore from git-synced refs/dolt/data or re-clone the remote per docs

Defensive patterns

Strategy: retry

Validate before calling

// ensure the workspace DB is reachable before remote ops
if _, err := os.Stat(filepath.Join(beadsDir, "beads.db")); err != nil {
  return fmt.Errorf("beads database missing: %w", err)
}

Try / catch

res, err := ensureDoltRemote(ctx, st, name, url, confirm)
if err != nil {
  if strings.Contains(err.Error(), "list existing remotes") {
    // transient server failure: back off and retry once
    time.Sleep(time.Second)
    return ensureDoltRemote(ctx, st, name, url, confirm)
  }
  return res, err
}

Prevention

Let bd start/stop its Dolt server; avoid killing it mid-operation
Run `bd doctor` if sync commands start failing on listing
Restore from git refs/dolt/data after any corruption instead of hacking the DB dir
Avoid concurrent bd processes on the same workspace

When it happens

Trigger: `bd dolt remote add` or `bd dolt push` when ListRemotes errors: the embedded Dolt server failed to start, database corruption, or driver-level I/O errors.

Common situations: Dolt server not running / crashed; another bd process holds conflicting state; corrupted .beads dolt directory after a crash or version downgrade.

Related errors

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