What causes "failed to add dolt remote: %w" in gastownhall/beads?

Check the wrapped inner error for the actual AddRemote failure reason.

failed to add dolt remote: %w

Error message

failed to add dolt remote: %w

What it means

After storing the credentials row, addFederationPeer registers the peer as a Dolt remote via s.AddRemote. This wraps any AddRemote failure that is not an 'already exists' error (duplicates are deliberately tolerated). It means the credentials were stored but the remote was not created, leaving the peer only partially configured.

Source

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

		INSERT INTO federation_peers (name, remote_url, username, password_encrypted, sovereignty)
		VALUES (?, ?, ?, ?, ?)
		ON DUPLICATE KEY UPDATE
			remote_url = VALUES(remote_url),
			username = VALUES(username),
			password_encrypted = VALUES(password_encrypted),
			sovereignty = VALUES(sovereignty),
			updated_at = CURRENT_TIMESTAMP
	`, peer.Name, peer.RemoteURL, peer.Username, encryptedPwd, peer.Sovereignty)

	if err != nil {
		return fmt.Errorf("failed to add federation peer: %w", err)
	}

	// Also add the Dolt remote.
	if err := s.AddRemote(ctx, peer.Name, peer.RemoteURL); err != nil {
		// Ignore "remote already exists" errors
		if !strings.Contains(err.Error(), "already exists") {
			return fmt.Errorf("failed to add dolt remote: %w", err)
		}
	}

	if err := s.doltAddAndCommit(ctx, []string{"federation_peers"}, "federation: add peer "+peer.Name); err != nil {
		return fmt.Errorf("failed to commit federation peer: %w", err)
	}

	return nil
}

// GetFederationPeer retrieves a federation peer by name.
// Returns storage.ErrNotFound (wrapped) if the peer does not exist.
func (s *DoltStore) GetFederationPeer(ctx context.Context, name string) (*storage.FederationPeer, error) {
	var peer storage.FederationPeer
	var encryptedPwd []byte
	var lastSync sql.NullTime
	var username sql.NullString

View on GitHub (pinned to 71377f2769)

Solutions

Check the wrapped inner error for the actual AddRemote failure reason.
Validate peer.RemoteURL (scheme, host) before calling AddFederationPeer.
Verify the installed dolt CLI supports the remote URL scheme and works manually (`dolt remote add <name> <url>`).
Since credentials were already stored, fix the URL/remote issue and re-run AddFederationPeer — the upsert makes it idempotent.

Example fix

// before
peer.RemoteURL = "htps://dolthub.com/org/repo"
// after
peer.RemoteURL = "https://dolthub.com/org/repo"

Defensive patterns

Strategy: validation

Validate before calling

u, err := url.Parse(peer.RemoteURL)
if err != nil || u.Scheme == "" || u.Host == "" {
    return fmt.Errorf("invalid remote URL %q", peer.RemoteURL)
}

Try / catch

if err := store.AddFederationPeer(ctx, peer); err != nil && strings.Contains(err.Error(), "failed to add dolt remote") {
    // credentials were stored; fix URL/remote and re-run (upsert is idempotent)
}

Prevention

Validate remote URLs (scheme + host) before adding peers
Test `dolt remote add` manually with the same URL first
Re-run AddFederationPeer after fixing — the upsert makes it safe

When it happens

Trigger: AddRemote fails for a non-duplicate reason: the remote URL is malformed or uses an unsupported scheme, the dolt CLI subprocess fails, the remote name is reserved, or network/filesystem errors occur during remote registration.

Common situations: Typo in peer.RemoteURL (e.g. 'htps://'); URL scheme not supported by the installed dolt version; filesystem permission problems in the Dolt CLI directory during server-mode remote materialization.

Related errors

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