gastownhall/beads · error

peer remote %q uses git protocol and requires CLI routing: %

Error message

peer remote %q uses git protocol and requires CLI routing: %w

What it means

Wraps a failure from s.ensureMatchingCLIRemote after detecting that the peer's Dolt remote URL uses git protocol. The store must mirror the remote in the CLI database so pushes/pulls can be routed through the dolt CLI; if that mirror creation/update fails, git-protocol routing cannot proceed.

Source

Thrown at internal/storage/dolt/federation.go:640

// before routing.
func (s *DoltStore) prepareCLIRouteForPeerGitProtocol(ctx context.Context, peer string) (bool, error) {
	if s.CLIDir() == "" {
		return false, nil
	}
	if !s.hasCLIDatabase() {
		return false, nil
	}
	remotes, err := s.ListRemotes(ctx)
	if err != nil {
		return false, fmt.Errorf("list Dolt remotes before git-protocol routing for peer %q: %w", peer, err)
	}
	for _, r := range remotes {
		if r.Name == peer {
			if !doltutil.IsGitProtocolURL(r.URL) {
				return false, nil
			}
			if err := s.ensureMatchingCLIRemote(peer, r.URL); err != nil {
				return false, fmt.Errorf("peer remote %q uses git protocol and requires CLI routing: %w", peer, err)
			}
			return true, nil
		}
	}
	return false, nil
}

func (s *DoltStore) shouldUseCLIForPeerGitProtocol(ctx context.Context, peer string) (bool, error) {
	return s.prepareCLIRouteForPeerGitProtocol(ctx, peer)
}

// doltCLIPushRefToPeer shells out to `dolt push` with a specific refspec.
// The refspec can be a branch name or a "local:remote" mapping.
func (s *DoltStore) doltCLIPushRefToPeer(ctx context.Context, peer string, refspec string, creds *remoteCredentials) error {
	if err := s.prePushFSCK(ctx); err != nil {
		return err
	}
	cmd, transferCtx, cancel := s.prepareDoltCLITransfer(ctx, peer, creds, "push", peer, refspec)

View on GitHub (pinned to 71377f2769)

Solutions

1. Run `dolt remote add <peer> <url>` manually in the CLI database dir to see the CLI error
2. Verify the peer git URL is reachable and credentials (SSH key/token) are configured
3. Remove any stale conflicting remote entry in the CLI database and retry
4. Confirm the dolt CLI version supports the git-protocol remote URL scheme used

for _, u := range []string{peerURL} {
	parsed, err := url.Parse(u)
	if err != nil || parsed.Scheme == "" { return fmt.Errorf("invalid peer remote URL %q", u) }
}
if err := exec.Command("git", "ls-remote", peerURL).Run(); err != nil {
	return fmt.Errorf("peer git remote unreachable: %w", err)
}

When it happens

Trigger: prepareCLIRouteForPeerGitProtocol finds the peer remote in ListRemotes output, IsGitProtocolURL(r.URL) is true, and ensureMatchingCLIRemote(peer, r.URL) fails to create or update the matching remote in the CLI database (CLI error, permission, invalid URL).

Common situations: Peer URL points to an unreachable or misconfigured git remote; CLI database is read-only; dolt CLI cannot authenticate to the git remote; stale remote entry with a conflicting URL in the CLI database.

Related errors

• failed to add dolt remote: %w
• failed to push to peer %s: %w
• list Dolt remotes before git-protocol routing for peer %q: %
• dolt remote add failed: %s: %w
• dolt remote remove failed: %s: %w

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