gastownhall/beads · error

failed to add federation peer: %w

Error message

failed to add federation peer: %w

What it means

This wraps the error from the SQL upsert INSERT ... ON DUPLICATE KEY UPDATE into the federation_peers table. It means the peer credentials row could not be written to the Dolt database — the peer was not added or updated.

Source

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

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

	// Upsert the peer credentials
	_, err = s.execContext(ctx, `
		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.

View on GitHub (pinned to 71377f2769)

Solutions

1. Check the wrapped inner error for the root cause (connection refused vs unknown table vs permission denied).
2. Run schema migrations / `bd init` to create the federation_peers table if it doesn't exist.
3. Verify the Dolt server is reachable and the SQL user has write privileges on the database.
4. Check disk space and that the store isn't in a read-only or circuit-open state; retry after restoring connectivity.

// Ensure the schema exists before writing
if _, err := db.Query("SELECT 1 FROM federation_peers LIMIT 1"); err != nil {
    return fmt.Errorf("run bd init / migrate schema first: %w", err)
}

if err := store.AddFederationPeer(ctx, peer); err != nil && strings.Contains(err.Error(), "failed to add federation peer") {
    var netErr net.Error
    if errors.As(err, &netErr) || strings.Contains(err.Error(), "connection") {
        // retry after restoring Dolt server connectivity
    }
}

When it happens

Trigger: The INSERT/UPSERT statement fails: federation_peers table missing (schema not migrated), database connection lost, constraint violations, or the Dolt server rejecting the write (read-only replica, closed circuit breaker via withCircuitWrite).

Common situations: Running bd against a database created by an older version without the federation_peers table; external dolt-sql-server restarted or unreachable; disk full on the Dolt data directory; connecting with a read-only SQL user.

Related errors

• add federation peer: %w
• get federation peer: %w
• list federation peers: %w
• remove federation peer: %w
• failed to begin transaction: %w

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