list Dolt remotes before credential routing for peer %q: %w

Error message

list Dolt remotes before credential routing for peer %q: %w

What it means

In server mode, before routing credential-bearing peer operations through the Dolt CLI, bd lists SQL-visible remotes to decide routing. This error wraps a ListRemotes failure during that pre-flight for a peer. The library throws it because it can't safely choose between SQL-path and CLI-path credential handling without knowing the remote set.

Source

Thrown at internal/storage/dolt/credentials.go:643

	return err
}

// FederationPeer is an alias for storage.FederationPeer for convenience.
type FederationPeer = storage.FederationPeer

func (s *DoltStore) prepareCLIRouteForPeerCredentials(ctx context.Context, peer string, creds *remoteCredentials) (bool, error) {
	if creds.empty() {
		return false, nil // no credentials to pass
	}
	if !s.serverMode {
		return false, nil // embedded mode: withEnvCredentials works in-process
	}
	if !s.hasCLIDatabase() {
		return false, nil
	}
	remotes, err := s.ListRemotes(ctx)
	if err != nil {
		return false, fmt.Errorf("list Dolt remotes before credential routing for peer %q: %w", peer, err)
	}
	for _, r := range remotes {
		if r.Name == peer {
			if err := s.ensureMatchingCLIRemote(peer, r.URL); err != nil {
				return false, fmt.Errorf("peer remote %q has credentials and requires CLI routing: %w", peer, err)
			}
			return true, nil
		}
	}
	return false, nil
}

func (s *DoltStore) shouldUseCLIForPeerCredentialsWithError(ctx context.Context, peer string, creds *remoteCredentials) (bool, error) {
	return s.prepareCLIRouteForPeerCredentials(ctx, peer, creds)
}

// shouldUseCLIForCredentials returns true when CLI subprocess routing should
// be used instead of SQL path for credential-bearing push/pull operations.

View on GitHub (pinned to 71377f2769)

Solutions

Check the dolt-sql-server is running and reachable; restart it if needed, then retry the sync.
Retry the operation — this is often transient (connection reset).
Verify the store's connection isn't stale after a server restart; reopen the store.
Check the Dolt server logs for the underlying query error to fix root cause (locks, corruption).

Example fix

// before
ok, err := shouldUseCLIForPeerCredentialsWithError(ctx, "peer", creds) // list Dolt remotes ... connection refused
// after: ensure server is up, then retry
// dolt sql-server &
ok, err := shouldUseCLIForPeerCredentialsWithError(ctx, "peer", creds)

Defensive patterns

Strategy: retry

Validate before calling

// probe SQL connectivity before the routing pre-flight
if err := db.PingContext(ctx); err != nil { /* restart/reconnect dolt-sql-server first */ }

Try / catch

ok, err := shouldUseCLIForPeerCredentialsWithError(ctx, peer, creds)
if err != nil && strings.Contains(err.Error(), "list Dolt remotes before credential routing") {
    time.Sleep(2 * time.Second)
    ok, err = shouldUseCLIForPeerCredentialsWithError(ctx, peer, creds)
}

Prevention

Supervise dolt-sql-server with auto-restart
Use fresh contexts per operation, not long-lived cancelled ones
Monitor connection pool health in long-running processes
Retry transient SQL errors with exponential backoff

When it happens

Trigger: prepareCLIRouteForPeerCredentials calls ListRemotes and the underlying query against the Dolt SQL server fails: server down/restarted, connection dropped, context cancelled, or database locked. Requires server mode + a CLI database + non-empty creds to even reach this point.

Common situations: dolt-sql-server crashed between operations; transient network failure to a remote server; long-running session whose connection timed out right before a push/pull.

Related errors

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