gastownhall/beads · error

connect to dolt server for clone: %w

Error message

connect to dolt server for clone: %w

What it means

Wrapped by cloneViaServer in cmd/bd/bootstrap.go:961 when sql.Open("mysql", dsn) fails to construct a connection to the external Dolt sql-server using the configured DSN (socket/host/port/user/password/TLS). sql.Open only validates the DSN format and driver availability, so this usually means a malformed DSN configuration value.

Source

Thrown at cmd/bd/bootstrap.go:961

// cloneViaServer clones by connecting to the external Dolt server and
// executing CALL DOLT_CLONE. The server places the database in its own
// data directory, which is the correct behavior for externally managed
// servers where bd does not know the filesystem layout.
func cloneViaServer(ctx context.Context, beadsDir, remoteURL, dbName string, cfg *configfile.Config) error {
	port := serverClonePort(beadsDir, cfg)
	dsn := doltutil.ServerDSN{
		Socket:   cfg.GetDoltServerSocket(),
		Host:     cfg.GetDoltServerHost(),
		Port:     port,
		User:     cfg.GetDoltServerUser(),
		Password: cfg.GetDoltServerPasswordForPort(port),
		TLS:      cfg.GetDoltServerTLS(),
		// No Database — DOLT_CLONE creates the database.
	}.String()

	db, err := sql.Open("mysql", dsn)
	if err != nil {
		return fmt.Errorf("connect to dolt server for clone: %w", err)
	}
	defer db.Close()

	cloneCtx, cancel := context.WithTimeout(ctx, 5*time.Minute)
	defer cancel()

	if err := db.PingContext(cloneCtx); err != nil {
		return fmt.Errorf("dolt server unreachable at %s:%d (is dolt sql-server running?): %w",
			cfg.GetDoltServerHost(), port, err)
	}

	if err := versioncontrolops.DoltClone(cloneCtx, db, remoteURL, dbName, os.Getenv("DOLT_REMOTE_USER")); err != nil {
		return fmt.Errorf("clone from remote via server: %w", err)
	}
	fmt.Fprintf(os.Stderr, "Synced database from %s (via server at %s:%d)\n",
		remoteURL, cfg.GetDoltServerHost(), port)
	return nil
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Inspect dolt_server fields in .beads/metadata.json and fix host/port/socket/user values
2. If the password contains special characters, quote/escape it or reset it to a URL-safe value
3. Verify TLS setting is a valid value per doltutil.ServerDSN
4. Re-run bd bootstrap after correcting config

Example fix

// before: metadata.json has dolt_server.socket: "/tmp/my server.sock" (space breaks DSN)
// after: move server socket to a clean path
$ bd update-config  # or edit metadata.json: "socket": "/tmp/beads-dolt.sock"
$ bd bootstrap

// validate server config before clone
cfg, _ := configfile.Load(beadsDir)
if cfg.GetDoltServerSocket() == "" && cfg.GetDoltServerHost() == "" {
	return errors.New("neither socket nor host configured for dolt server")
}
if cfg.GetDoltServerSocket() != "" {
	if _, err := os.Stat(cfg.GetDoltServerSocket()); err != nil {
		return fmt.Errorf("socket path invalid: %w", err)
	}
}

err := cloneViaServer(ctx, dir, url, db, cfg)
if err != nil {
	if strings.Contains(err.Error(), "connect to dolt server for clone") {
		// DSN malformed: inspect dolt_server fields in metadata.json
	}
}

When it happens

Trigger: cloneFromRemoteWithMode resolves external-server mode and calls cloneViaServer; sql.Open errors on an invalid DSN — e.g., malformed socket path, invalid characters in host/user/password from metadata.json, or bad TLS setting string.

Common situations: Typos in dolt_server.host/socket fields in .beads/metadata.json; special characters (like @ or /) in a password not escaped correctly; empty/invalid TLS config value.

Related errors

• server: NewDoltServer: doltBinExec is required
• server: NewDoltServer: rootDir is required
• server: NewDoltServer: configPath is required
• ErrPrefixMismatch
• failed to find backup directory: %w

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