What causes "list federation peers: %w" in gastownhall/beads?

Read the wrapped driver error to identify the root cause

list federation peers

Error message

list federation peers: %w

What it means

ListFederationPeersInTx failed while querying federation_peers; the driver error is wrapped as "list federation peers". This is a database-level failure (missing table, connection, schema), not an empty result. An empty table returns an empty slice with nil error.

Solutions

Read the wrapped driver error to identify the root cause
Run pending schema migrations to create federation_peers
Retry if the error is transient (connection reset)
Confirm you are connected to the intended database

Example fix

// before
peers, err := issueops.ListFederationPeersInTx(ctx, tx) // fails: table not found
// after
if err := migrate(ctx, db); err != nil { // ensure federation_peers exists
    return err
}
peers, err := issueops.ListFederationPeersInTx(ctx, tx)

Defensive patterns

Strategy: retry

Validate before calling

// ensure federation_peers exists before listing
if err := migrate(ctx, db); err != nil {
    return err
}

Try / catch

var peers []*issueops.FederationPeerRow
var err error
for i := 0; i < 3; i++ {
    peers, err = issueops.ListFederationPeersInTx(ctx, tx)
    if err == nil || errors.Is(ctx.Err(), context.Canceled) {
        break
    }
    time.Sleep(time.Duration(1<<i) * 100 * time.Millisecond) // transient-error backoff
}
if err != nil {
    return fmt.Errorf("list peers: %w", err)
}

Prevention

Retry transient driver errors with backoff
Run migrations on startup so tables always exist
Distinguish empty results (nil error) from query failures

When it happens

Trigger: tx.QueryContext on federation_peers returns a driver error: table missing (migration not run), connection refused/reset, or schema mismatch.

Common situations: Fresh database before migrations; Dolt server down; running a newer binary against an older schema where federation_peers doesn't exist.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

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

Appendix: source

Thrown at internal/storage/issueops/federation.go:100

	if username.Valid {
		row.Peer.Username = username.String
	}
	if lastSync.Valid {
		row.Peer.LastSync = &lastSync.Time
	}

	return &row, nil
}

// ListFederationPeersInTx returns all configured federation peer rows.
func ListFederationPeersInTx(ctx context.Context, tx *sql.Tx) ([]*FederationPeerRow, error) {
	rows, err := tx.QueryContext(ctx, `
		SELECT name, remote_url, username, password_encrypted, sovereignty, last_sync, created_at, updated_at
		FROM federation_peers ORDER BY name
	`)
	if err != nil {
		return nil, fmt.Errorf("list federation peers: %w", err)
	}
	defer rows.Close()

	var peers []*FederationPeerRow
	for rows.Next() {
		var row FederationPeerRow
		var lastSync sql.NullTime
		var username sql.NullString

		if err := rows.Scan(
			&row.Peer.Name, &row.Peer.RemoteURL, &username, &row.EncryptedPwd,
			&row.Peer.Sovereignty, &lastSync, &row.Peer.CreatedAt, &row.Peer.UpdatedAt,
		); err != nil {
			return nil, fmt.Errorf("scan federation peer: %w", err)
		}

		if username.Valid {
			row.Peer.Username = username.String

View on GitHub (pinned to 71377f2769)