gastownhall/beads · error

clone from remote via server: %w

Error message

clone from remote via server: %w

What it means

Wrapped by cloneViaServer in cmd/bd/bootstrap.go:974 when versioncontrolops.DoltClone fails while executing CALL DOLT_CLONE through the connected external Dolt server. The connection succeeded; the clone itself failed on the server side — typically the server cannot reach the remote, lacks credentials, or the database already exists on the server.

Source

Thrown at cmd/bd/bootstrap.go:974

		// 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
}

func serverClonePort(beadsDir string, cfg *configfile.Config) int {
	if cfg != nil && cfg.DoltServerPort > 0 {
		return cfg.DoltServerPort
	}
	if p := os.Getenv("BEADS_DOLT_SERVER_PORT"); p != "" {
		if port, err := strconv.Atoi(p); err == nil && port > 0 {
			return port
		}
	}
	if p := os.Getenv("BEADS_DOLT_PORT"); p != "" {
		if port, err := strconv.Atoi(p); err == nil && port > 0 {
			return port

View on GitHub (pinned to 71377f2769)

Solutions

1. Check the server host can reach the remote URL (curl/dolt clone from the server machine)
2. Drop the already-existing database on the server (`DROP DATABASE <dbName>`) if it is safe to re-clone, or use a different dbName
3. Configure/refresh Dolt credentials on the server machine for the remote account
4. For large databases, increase the timeout or pre-clone via the CLI path (owned-server mode)

Example fix

// before: db already exists on shared server
$ bd bootstrap
// error: clone from remote via server: database beads already exists
// after
$ dolt -r ~/beads-server sql -q 'DROP DATABASE beads'
$ bd bootstrap

// server needs outbound access to the remote and a free database name
// pre-check from the server machine:
curl -sI https://doltremoteapi.dolthub.com/org/beads | head -1
// ensure dbName does not already exist on the server:
dolt sql -q "SHOW DATABASES LIKE 'beads'"

err := cloneViaServer(ctx, dir, url, db, cfg)
if err != nil {
	if strings.Contains(err.Error(), "clone from remote via server") {
		// inspect server-side cause: egress, credentials, or existing database
		// optionally DROP DATABASE and retry
	}
}

When it happens

Trigger: DoltClone issues DOLT_CLONE over the MySQL connection and the server returns an error: server has no outbound network access to the remote URL, remote auth fails server-side, dbName already exists on the server (clone refuses to overwrite), or timeout for very large databases.

Common situations: Air-gapped/egress-restricted server host; database with the same name already cloned by a teammate on the shared server; expired Dolt credentials on the server machine; large repo exceeding the 5-minute cloneCtx timeout.

Related errors

• clone from remote: %w
• connect to dolt server for clone: %w
• dolt server unreachable at %s:%d (is dolt sql-server running
• sync from remote: %w
• --server-host cannot be empty; omit the flag to use BEADS_DO

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