{"record":{"id":"318b8fb672156cf7","repo":"gastownhall/beads","slug":"dolt-server-unreachable-at-s-d-is-dolt-sql-serv","errorCode":null,"errorMessage":"dolt server unreachable at %s:%d (is dolt sql-server running?): %w","messagePattern":"dolt server unreachable at (.+?):(.+?) \\(is dolt sql-server running\\?\\): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/bootstrap.go","lineNumber":969,"sourceCode":"\t\tHost:     cfg.GetDoltServerHost(),\n\t\tPort:     port,\n\t\tUser:     cfg.GetDoltServerUser(),\n\t\tPassword: cfg.GetDoltServerPasswordForPort(port),\n\t\tTLS:      cfg.GetDoltServerTLS(),\n\t\t// No Database — DOLT_CLONE creates the database.\n\t}.String()\n\n\tdb, err := sql.Open(\"mysql\", dsn)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"connect to dolt server for clone: %w\", err)\n\t}\n\tdefer db.Close()\n\n\tcloneCtx, cancel := context.WithTimeout(ctx, 5*time.Minute)\n\tdefer cancel()\n\n\tif err := db.PingContext(cloneCtx); err != nil {\n\t\treturn fmt.Errorf(\"dolt server unreachable at %s:%d (is dolt sql-server running?): %w\",\n\t\t\tcfg.GetDoltServerHost(), port, err)\n\t}\n\n\tif err := versioncontrolops.DoltClone(cloneCtx, db, remoteURL, dbName, os.Getenv(\"DOLT_REMOTE_USER\")); err != nil {\n\t\treturn fmt.Errorf(\"clone from remote via server: %w\", err)\n\t}\n\tfmt.Fprintf(os.Stderr, \"Synced database from %s (via server at %s:%d)\\n\",\n\t\tremoteURL, cfg.GetDoltServerHost(), port)\n\treturn nil\n}\n\nfunc serverClonePort(beadsDir string, cfg *configfile.Config) int {\n\tif cfg != nil && cfg.DoltServerPort > 0 {\n\t\treturn cfg.DoltServerPort\n\t}\n\tif p := os.Getenv(\"BEADS_DOLT_SERVER_PORT\"); p != \"\" {\n\t\tif port, err := strconv.Atoi(p); err == nil && port > 0 {\n\t\t\treturn port","sourceCodeStart":951,"sourceCodeEnd":987,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/bootstrap.go#L951-L987","documentation":"Wrapped by cloneViaServer in cmd/bd/bootstrap.go:969 when db.PingContext fails within a 5-minute timeout, meaning the external Dolt sql-server at the configured host:port did not accept the connection. bd explicitly reports the address and asks whether `dolt sql-server` is running, since clone via server mode depends entirely on a live server.","triggerScenarios":"External-server clone mode is selected but the server is not started, listening on a different port/socket than configured, rejecting credentials, or the network/firewall blocks the host:port.","commonSituations":"Forgot to start `dolt sql-server --data-dir ...` after reboot; port mismatch (BEADS_DOLT_SERVER_PORT vs actual server port); server bound to localhost while bd uses a container hostname; firewall/security-group blocking the port; wrong password causing access-denied inside the ping.","solutions":["Start the Dolt server: run `dolt sql-server` in the server data directory (or bd's owned-server flow)","Verify the server address matches config: check dolt_server host/port in .beads/metadata.json and BEADS_DOLT_SERVER_PORT env","Test connectivity manually: `mysql -h <host> -P <port> -u <user> -p` or `dolt sql -q 'select 1'` against the server","Check firewalls/security groups if the server is remote; confirm the socket path exists if using socket mode"],"exampleFix":"// before\n$ bd bootstrap\n// error: dolt server unreachable at localhost:3307 (is dolt sql-server running?)\n// after\n$ cd ~/beads-server && dolt sql-server &\n$ sleep 2 && bd bootstrap   # Synced database from ... (via server at localhost:3307)","handlingStrategy":"retry","validationCode":"// probe the server before attempting clone\nhost, port := \"localhost\", 3307\nconn, err := net.DialTimeout(\"tcp\", fmt.Sprintf(\"%s:%d\", host, port), 3*time.Second)\nif err != nil { return fmt.Errorf(\"start dolt sql-server first: %w\", err) }\nconn.Close()","typeGuard":null,"tryCatchPattern":"err := cloneViaServer(ctx, dir, url, db, cfg)\nvar netErr net.Error\nif err != nil && errors.As(err, &netErr) {\n\t// server unreachable: start/restart dolt sql-server, wait, retry with backoff\n\ttime.Sleep(5 * time.Second)\n\terr = cloneViaServer(ctx, dir, url, db, cfg)\n}","preventionTips":["Always start `dolt sql-server` in the server data directory before bd bootstrap in server mode","Keep BEADS_DOLT_SERVER_PORT / metadata.json port in sync with the actual server port","For remote servers, verify firewall/security-group rules allow the MySQL port","Use health checks/wait loops in CI before invoking bd bootstrap against a server"],"tags":["network","mysql","dolt-server","connection"],"backgroundTag":"connection-refused","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}