gastownhall/beads · error

list Dolt remotes before credential routing for remote %q: %

Error message

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

What it means

prepareCLIRouteForCredentials lists SQL-visible Dolt remotes to decide whether a credential-bearing push/pull must go through the CLI subprocess instead of CALL DOLT_PUSH/PULL. This error wraps a ListRemotes failure during that pre-flight for a remote. Without the remote list, bd cannot safely route credentials, so it returns the wrapped error (or logs a warning and falls back to the SQL path via shouldUseCLIForCredentials).

Source

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

		log.Printf("warning: %v", err)
		return false
	}
	return ok
}

func (s *DoltStore) prepareCLIRouteForCredentials(ctx context.Context, remote 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 remote %q: %w", remote, err)
	}
	for _, r := range remotes {
		if r.Name == remote {
			if err := s.ensureMatchingCLIRemote(remote, r.URL); err != nil {
				return false, fmt.Errorf("remote %q has credentials and requires CLI routing: %w", remote, err)
			}
			return true, nil
		}
	}
	return false, nil
}

func (s *DoltStore) shouldUseCLIForCredentialsWithError(ctx context.Context, remote string, creds *remoteCredentials) (bool, error) {
	return s.prepareCLIRouteForCredentials(ctx, remote, creds)
}

func (s *DoltStore) shouldUseCLIForLocalRemoteWithError(ctx context.Context, remote string) (bool, error) {
	if !s.serverMode {

View on GitHub (pinned to 71377f2769)

Solutions

1. Verify dolt-sql-server is running and reachable; restart it and reopen the store if needed.
2. Retry the push/pull — transient connection errors often clear.
3. Check the Dolt server logs for the underlying ListRemotes failure and fix the root cause.
4. As a workaround, run in embedded mode where credential routing doesn't need this pre-flight.

Example fix

// before: server down
pushToRemote(...) // list Dolt remotes before credential routing for remote "origin": connection refused
// after
# systemctl restart dolt-sql-server
pushToRemote(...)

// verify the SQL server answers before push/pull routing
if err := db.PingContext(ctx); err != nil { /* reconnect or restart server */ }

if err := pushToRemote(ctx, remote); err != nil && strings.Contains(err.Error(), "list Dolt remotes before credential routing") {
    // transient server issue — reconnect and retry once
    store.Reconnect(ctx)
    err = pushToRemote(ctx, remote)
}

When it happens

Trigger: ListRemotes fails because the dolt-sql-server is down or the connection dropped, the context is cancelled, or the query errors (locks, missing dolt database in the server). Reached only when creds are non-empty and the store is in server mode with a CLI database.

Common situations: Pushing to an authenticated remote right after the external SQL server was restarted; transient network issues with a remote dolt-sql-server; stale client connections in a long-lived process.

Related errors

• list Dolt remotes before credential routing for peer %q: %w
• peer remote %q has credentials and requires CLI routing: %w
• list remotes: %w
• ErrTransaction
• ErrQuery

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