peer remote %q has credentials and requires CLI routing: %w

Error message

peer remote %q has credentials and requires CLI routing: %w

What it means

When a peer has stored credentials and a matching Dolt remote exists, bd must materialize that remote into the local CLI directory before routing the operation through the CLI subprocess. This error wraps ensureMatchingCLIRemote failing during that setup — the CLI route was required but could not be prepared. The library throws it rather than silently falling back to the SQL path, which would fail authentication with an external server.

Source

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

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.
//
// When true, callers should route through doltCLIPush/Pull instead of
// CALL DOLT_PUSH/PULL, because withEnvCredentials() sets env vars on the
// bd client process — the external server process cannot see them.
//

View on GitHub (pinned to 71377f2769)

Solutions

Ensure the dolt CLI binary is installed and on PATH (dolt version).
Verify the local CLI database directory (.beads/dolt) exists and is writable; re-initialize if corrupt.
Confirm the remote URL matches between the SQL server and CLI dir; remove and re-add the peer so both sides re-sync.
If CLI routing is unnecessary for your setup, clear the peer's stored credentials or run in embedded mode where the SQL path handles env credentials in-process.

Example fix

// before: dolt missing on PATH in server mode
ok, err := shouldUseCLIForPeerCredentialsWithError(ctx, "peer", creds) // requires CLI routing: exec: "dolt": executable file not found
// after: install dolt CLI and ensure CLI db is initialized
brew install dolt || sudo apt-get install dolt
ok, err = shouldUseCLIForPeerCredentialsWithError(ctx, "peer", creds)

Defensive patterns

Strategy: validation

Validate before calling

// before credential routing, verify CLI prerequisites
if _, err := exec.LookPath("dolt"); err != nil {
    return fmt.Errorf("dolt CLI required for credential routing in server mode: %w", err)
}
if info, err := os.Stat(cliDoltDir); err != nil || !info.IsDir() {
    return fmt.Errorf("CLI database dir %s missing", cliDoltDir)
}

Try / catch

ok, err := shouldUseCLIForPeerCredentialsWithError(ctx, peer, creds)
if err != nil && strings.Contains(err.Error(), "requires CLI routing") {
    // fix dolt CLI/CLI dir, or fall back: clear peer creds to avoid CLI routing
    log.Printf("CLI route unavailable: %v", err)
}

Prevention

Install the dolt CLI on hosts running server-mode bd
Keep the local CLI database directory initialized and writable
Keep remote URLs identical between SQL server and CLI dir
Run all bd processes as the same user to avoid permission drift

When it happens

Trigger: ensureMatchingCLIRemote fails to create/update the peer remote in the CLI database directory: the local .beads/dolt CLI dir is missing/corrupt, the dolt CLI binary is unavailable or fails, file permissions block the CLI directory, or the remote URL can't be materialized.

Common situations: Server mode (external dolt-sql-server) with peer credentials where the local CLI database directory wasn't initialized; dolt binary not on PATH; mismatched remote URL between SQL and CLI dirs; permissions on .beads/dolt after running as different users.

Related errors

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