{"record":{"id":"3a0d1371449dfbba","repo":"gastownhall/beads","slug":"ensure-global-db-server-not-reachable-w","errorCode":null,"errorMessage":"ensure global db: server not reachable: %w","messagePattern":"ensure global db: server not reachable: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/doltserver/doltserver.go","lineNumber":1544,"sourceCode":"\tctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)\n\tdefer cancel()\n\n\tdsn := doltutil.ServerDSN{\n\t\tHost:     host,\n\t\tPort:     port,\n\t\tUser:     user,\n\t\tPassword: password,\n\t}.String()\n\tdb, err := sql.Open(\"mysql\", dsn)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"ensure global db: failed to open connection: %w\", err)\n\t}\n\tdefer db.Close()\n\tdb.SetMaxOpenConns(1)\n\tdb.SetConnMaxLifetime(10 * time.Second)\n\n\tif err := db.PingContext(ctx); err != nil {\n\t\treturn fmt.Errorf(\"ensure global db: server not reachable: %w\", err)\n\t}\n\n\t// CREATE DATABASE IF NOT EXISTS is idempotent — safe on every call.\n\t// GlobalDatabaseName is a constant (\"beads_global\"), not user input.\n\t_, err = db.ExecContext(ctx, fmt.Sprintf(\"CREATE DATABASE IF NOT EXISTS `%s`\", GlobalDatabaseName)) //nolint:gosec // G201: constant database name\n\tif err != nil {\n\t\terrLower := strings.ToLower(err.Error())\n\t\tif !strings.Contains(errLower, \"database exists\") && !strings.Contains(errLower, \"1007\") {\n\t\t\treturn fmt.Errorf(\"ensure global db: failed to create %s: %w\", GlobalDatabaseName, err)\n\t\t}\n\t}\n\n\treturn nil\n}\n\n// FlushWorkingSet connects to the running Dolt server and commits any uncommitted\n// working set changes across all databases. This prevents data loss when the server\n// is about to be stopped or restarted. Returns nil if there's nothing to flush or","sourceCodeStart":1526,"sourceCodeEnd":1562,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/doltserver/doltserver.go#L1526-L1562","documentation":"EnsureGlobalDatabase wraps db.PingContext failure with this message: the DSN parsed, but no reachable MySQL-protocol server answered at host:port within the 10-second context timeout. This means the dolt sql-server is not running, listening elsewhere, or refusing/dropping connections — the global beads_global database cannot be created.","triggerScenarios":"db.PingContext(ctx) returns an error on a freshly opened connection to the shared dolt server — server never started or already exited, wrong host/port configuration, connection refused, auth rejected, TLS mismatch, or the 10s ctx deadline elapsed first.","commonSituations":"Shared server managed by systemd crashed or was never started; another developer's server on a different port in BEADS_DB_PORT; Docker network/hostname misconfiguration; firewall blocking the port; wrong password in shared config; server overloaded and not accepting within 10s.","solutions":["Confirm the server is up: bd dolt status, or nc -vz <host> <port>; start it with bd dolt start if down","Verify host/port/credentials in bd config / BEADS_DB_HOST / BEADS_DB_PORT match the actual server","Read the wrapped error: 'connection refused' = wrong port or dead server; 'timeout' = firewall/routing; 'access denied' = wrong user/password","Check container/network reachability (docker network, VPN, security groups) if the server runs remotely","If the server is up but slow, investigate server load — the ping window is fixed at 10s"],"exampleFix":"// before\n// error: ensure global db: server not reachable: dial tcp 10.0.0.5:3307: connect: connection refused\n// after: point config at the live server (or start it)\n// $ bd dolt start\n// $ bd config set dolt.shared-server-host 10.0.0.5\n// $ bd config set dolt.shared-server-port 3308","handlingStrategy":"retry","validationCode":"// Reachability pre-check before EnsureGlobalDatabase\nconn, err := net.DialTimeout(\"tcp\", net.JoinHostPort(host, strconv.Itoa(port)), 3*time.Second)\nif err != nil {\n    return fmt.Errorf(\"dolt server not listening on %s:%d — run bd dolt start\", host, port)\n}\nconn.Close()","typeGuard":null,"tryCatchPattern":"err := doltserver.EnsureGlobalDatabase(host, port, user, password)\nif err != nil && strings.Contains(err.Error(), \"server not reachable\") {\n    // one bounded retry after a short wait — server may still be starting\n    time.Sleep(2 * time.Second)\n    if retryErr := doltserver.EnsureGlobalDatabase(host, port, user, password); retryErr != nil {\n        return fmt.Errorf(\"ensure global db failed (is the server up? bd dolt status): %w\", retryErr)\n    }\n    return nil\n}\nif err != nil { return err }\nreturn nil","preventionTips":["Run bd dolt status before operations that need the shared server","Use a process manager (systemd) so the shared server auto-restarts","Keep host/port config in sync across the team (BEADS_DB_HOST/BEADS_DB_PORT)","Alert on server uptime if the shared server is remote","Remember the 10s ping window; investigate load if pings intermittently time out"],"tags":["go","mysql","network","ping","dolt-server"],"backgroundTag":"server-not-reachable","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}