gastownhall/beads · warning

flush: server not reachable: %w

Error message

flush: server not reachable: %w

What it means

FlushWorkingSet wraps db.PingContext failure with this message: the DSN was valid but no server answered at host:port within the 10-second context timeout, so uncommitted working-set changes cannot be flushed before the server stops. FlushWorkingSet is best-effort — StopWithForce logs a warning and continues the shutdown, risking loss of uncommitted changes.

Source

Thrown at internal/doltserver/doltserver.go:1582

func FlushWorkingSet(host string, port int) error {
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	dsn := doltutil.ServerDSN{
		Host: host,
		Port: port,
		User: "root",
	}.String()
	db, err := sql.Open("mysql", dsn)
	if err != nil {
		return fmt.Errorf("flush: failed to open connection: %w", err)
	}
	defer db.Close()
	db.SetMaxOpenConns(1)
	db.SetConnMaxLifetime(10 * time.Second)

	if err := db.PingContext(ctx); err != nil {
		return fmt.Errorf("flush: server not reachable: %w", err)
	}

	// List all databases, skipping system databases
	rows, err := db.QueryContext(ctx, "SHOW DATABASES")
	if err != nil {
		return fmt.Errorf("flush: failed to list databases: %w", err)
	}
	var databases []string
	for rows.Next() {
		var name string
		if err := rows.Scan(&name); err != nil {
			continue
		}
		// Skip Dolt system databases
		if name == "information_schema" || name == "mysql" || name == "performance_schema" {
			continue
		}
		databases = append(databases, name)

View on GitHub (pinned to 71377f2769)

Solutions

1. Check whether the server is actually running (bd dolt status / ps aux | grep dolt); if it died, restart it — bd dolt start — and commit pending work
2. Delete stale state files (.beads/dolt-server.pid, .beads/dolt-server.port) and retry bd dolt stop so the correct port is used
3. If the wrapped error is a timeout, retry — a loaded server may answer within the window on a second attempt
4. Check network reachability to a remote shared server (ping/nc) if host is remote
5. If uncommitted data was lost, inspect dolt logs / data dir; consider bd doctor --fix only if corruption is indicated

Example fix

// before
// Warning: could not flush working set before stop: flush: server not reachable: dial tcp 127.0.0.1:41017: connect: connection refused
// after: clear stale state and flush via a live server
// $ bd dolt start      # or verify the port file matches the live server
// $ bd dolt stop       # flush now succeeds before shutdown

// Confirm the server is alive and the port file matches before stopping
state, err := doltserver.IsRunning(beadsDir)
if err != nil { return err }
if !state.Running {
    return errors.New("server already down; nothing to flush")
}
conn, err := net.DialTimeout("tcp", fmt.Sprintf("%s:%d", host, state.Port), 2*time.Second)
if err != nil {
    return fmt.Errorf("server dead on port %d; remove stale pid/port files and restart", state.Port)
}
conn.Close()

err := doltserver.FlushWorkingSet(host, port)
if err != nil && strings.Contains(err.Error(), "server not reachable") {
    // one retry after a short pause — server may have been mid-restart
    time.Sleep(time.Second)
    if err := doltserver.FlushWorkingSet(host, port); err != nil {
        log.Printf("warning: flush failed after retry: %v — uncommitted changes at risk", err)
    }
}

When it happens

Trigger: db.PingContext(ctx) fails during a bd dolt stop/restart: the server died before the flush, wrong port read from the port file of a stale state, connection refused because the server already exited, or the 10s timeout elapsed on a loaded server.

Common situations: Server crashed mid-session so stop-time flush can't connect (orphaned uncommitted changes); stale .beads/dolt-server.port pointing at a dead or reused port; remote shared server network blip during shutdown; slow server under heavy write load exceeding the 10s ping window.

Related errors

• ensure global db: server not reachable: %w
• flush: failed to open connection: %w
• flush: failed to list databases: %w
• open gc connection: %w
• acquire gc connection: %w

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