gastownhall/beads · error

failed to push to peer %s: %w

Error message

failed to push to peer %s: %w

What it means

Federation push to a peer failed: the CALL DOLT_PUSH('<peer>', '<refspec>') stored procedure returned an error. Causes include the peer not being configured as a Dolt remote, authentication/credential failure, the refspec not existing locally, or network failure reaching the peer. The peer name and underlying error are wrapped for diagnosis.

Source

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

// pushRefToPeer pushes a specific refspec to a peer remote. The refspec can be
// a simple branch name ("main") or a mapping ("staging:main").
func (s *DoltStore) pushRefToPeer(ctx context.Context, peer string, refspec string) error {
	if useCLI, err := s.prepareCLIRouteForPeerGitProtocol(ctx, peer); err != nil {
		return err
	} else if useCLI {
		return s.withPeerCredentials(ctx, peer, func(creds *remoteCredentials) error {
			return s.doltCLIPushRefToPeer(ctx, peer, refspec, creds)
		})
	}
	return s.withPeerCredentials(ctx, peer, func(creds *remoteCredentials) error {
		if useCLI, err := s.prepareCLIRouteForPeerCredentials(ctx, peer, creds); err != nil {
			return err
		} else if useCLI {
			return s.doltCLIPushRefToPeer(ctx, peer, refspec, creds)
		}
		return withEnvCredentials(creds, func() error {
			if err := s.execWithLongTimeout(ctx, "CALL DOLT_PUSH(?, ?)", peer, refspec); err != nil {
				return fmt.Errorf("failed to push to peer %s: %w", peer, err)
			}
			return nil
		})
	})
}

// PullFrom pulls changes from a specific peer remote.
// If credentials are stored for this peer, they are used automatically.
// For git-protocol remotes, uses CLI `dolt pull` to avoid MySQL connection timeouts.
// Returns any merge conflicts if present.
func (s *DoltStore) PullFrom(ctx context.Context, peer string) ([]storage.Conflict, error) {
	var conflicts []storage.Conflict
	err := s.withCircuitWrite(ctx, func(ctx context.Context) error {
		var err error
		conflicts, err = s.pullFromPeer(ctx, peer)
		return err
	})
	return conflicts, err

View on GitHub (pinned to 71377f2769)

Solutions

1. Verify the peer is a configured Dolt remote (`dolt remote -v`) and the name matches your federation config.
2. Re-authenticate or refresh credentials (withEnvCredentials path) — check tokens/SSH keys haven't expired.
3. Confirm the refspec exists locally (`dolt branch`) and on the expected ref; create or re-fetch it if missing.
4. Test connectivity to the peer (curl/ssh the peer's endpoint); if the SQL path keeps failing, retry via the CLI path (dolt push) which gives clearer errors.

Example fix

// before: pushing an unconfigured peer
s.execWithLongTimeout(ctx, "CALL DOLT_PUSH(?, ?)", "staging", refspec)
// fatal: unknown remote 'staging'
// after: add the peer remote first
dolt remote add staging https://doltremoteapi.dolthub.com/org/staging-db
// then retry the push

// Shell: verify peer remote and local ref exist before pushing
dolt remote -v | grep -q "^peer" || { echo "peer remote not configured"; exit 1; }
dolt rev-parse --verify <refspec> || { echo "refspec missing locally"; exit 1; }

func IsPushToPeerError(err error) bool {
	return err != nil && strings.Contains(err.Error(), "failed to push to peer")
}

err := federation.PushToPeer(ctx, peer, refspec, creds)
if err != nil && strings.Contains(err.Error(), "failed to push to peer "+peer) {
	// fall back to CLI push which yields clearer auth errors
	return federation.PushToPeerViaCLI(ctx, peer, refspec, creds)
}

When it happens

Trigger: pushRefToPeer with the SQL path (non-CLI) calling execWithLongTimeout('CALL DOLT_PUSH(?, ?)', peer, refspec) when the peer remote is missing from config, credentials are rejected, the branch/ref doesn't exist, or the peer is unreachable.

Common situations: Federation peer renamed or removed but still referenced in config; SSH/HTTPS credentials expired; pushing a branch that was deleted locally; peer's Dolt server offline or firewall blocking the port; mixing CLI and SQL push paths with different credential setups.

Related errors

• dolt push failed: %w Output: %s
• failed to add dolt remote: %w
• failed to pull from peer %s: %w
• failed to fetch from peer %s: %w
• fetch failed: %w

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