gastownhall/beads · error

database server not running

Error message

database server not running

What it means

During readiness waiting, the backoff loop returns this error when s.Running(ctx) reports the database server is not running. It means the backend process failed to start or died before the readiness timeout elapsed, so the proxy cannot accept connections.

Source

Thrown at internal/storage/dbproxy/proxy/server.go:495

		defer func() { _ = backend.Close() }()
		defer func() { _ = client.Close() }()
		n, err := io.Copy(client, backend)
		p.stats.AddBytesBackendToClient(n)
		p.tracef("handleConn(%s) backend→client done (n=%d, err=%v)", addr, n, err)
		return err
	})
	return g.Wait()
}

func waitForServerReady(ctx context.Context, s server.DatabaseServer, timeout time.Duration) error {
	bo := backoff.NewExponentialBackOff()
	bo.InitialInterval = readyInitialBackoff
	bo.MaxInterval = readyMaxBackoff
	bo.MaxElapsedTime = timeout

	return backoff.Retry(func() error {
		if !s.Running(ctx) {
			return errors.New("database server not running")
		}
		dialCtx, cancel := context.WithTimeout(ctx, readyDialTimeout)
		defer cancel()
		conn, err := s.Dial(dialCtx)
		if err != nil {
			return err
		}
		_ = conn.Close()
		return nil
	}, backoff.WithContext(bo, ctx))
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Check the server log file (passed to NewDoltServer) for the underlying backend crash reason
2. Verify the Dolt database directory and config file are valid and the port is free
3. Re-run the dolt binary manually against the rootDir to see startup errors directly

Example fix

// before
err := waitForReady(ctx, 5*time.Second) // opaque 'not running'
// after
if err != nil {
    log.Fatalf("backend not ready: %v; see %s", err, logFilePath)
}

// pre-check binary and port availability before starting backend
if _, err := exec.LookPath(doltBin); err != nil { return err }
if ln, err := net.Listen("tcp", addr); err != nil { return fmt.Errorf("port in use: %w", err) }; ln.Close()

if err := waitForReady(ctx, timeout); err != nil {
    if strings.Contains(err.Error(), "database server not running") {
        // inspect backend log, then retry startup with backoff
        tailServerLog(logFilePath)
        return retryStart(ctx)
    }
    return err
}

When it happens

Trigger: Backend Dolt server exits during startup (bad config, port conflict, corrupted DB) while proxy waits for readiness; startup timeout expiring with the server still down.

Common situations: Invalid dolt_server config path; port already in use; dolt binary crashing on an incompatible database directory.

Related errors

• start database server: %w
• write pid file: %w
• no store is open for this workspace
• not found
• no absolute native user directory is available

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