gastownhall/beads · error

sync from remote: %w

Error message

sync from remote: %w

What it means

Wrapped by cloneViaCLI in cmd/bd/bootstrap.go:1010 when dolt.BootstrapFromRemoteWithDB fails. This path shells out to the dolt CLI (used in owned-server mode where bd manages the server lifecycle) to sync the database into the resolved .beads dolt directory. Failure means the dolt CLI clone/pull of the named database from the remote did not succeed.

Source

Thrown at cmd/bd/bootstrap.go:1010

			return port
		}
	}
	if resolved := doltserver.DefaultConfig(beadsDir); resolved.Port > 0 {
		return resolved.Port
	}
	if cfg != nil {
		return cfg.GetDoltServerPort()
	}
	return configfile.DefaultDoltServerPort
}

// cloneViaCLI clones by shelling out to the dolt CLI.
// Used for owned-server mode where bd manages the server lifecycle.
func cloneViaCLI(ctx context.Context, beadsDir, remoteURL, dbName string) error {
	doltDir := doltserver.ResolveDoltDir(beadsDir)
	synced, err := dolt.BootstrapFromRemoteWithDB(ctx, doltDir, remoteURL, dbName)
	if err != nil {
		return fmt.Errorf("sync from remote: %w", err)
	}
	if synced {
		fmt.Fprintf(os.Stderr, "Synced database from %s\n", remoteURL)
	}
	return nil
}

func inferPrefix(cfg *configfile.Config) string {
	db := cfg.GetDoltDatabase()
	if db != "" && db != "beads" {
		return db
	}
	cwd, _ := os.Getwd()
	return filepath.Base(cwd)
}

// isNonInteractiveBootstrap returns true if bootstrap should skip confirmation prompts.
// Precedence: explicit flag > BD_NON_INTERACTIVE env > CI env > terminal detection.

View on GitHub (pinned to 71377f2769)

Solutions

1. Install or fix the dolt CLI: verify `dolt version` on PATH and upgrade to a current release
2. Test the remote manually: `dolt clone <remoteURL>` in a temp dir to surface the real cause (auth/DNS/URL)
3. Set correct Dolt credentials (dolt config --global user.email / remote credentials) and DOLT_REMOTE_USER if needed
4. If .beads/dolt is corrupted from a partial clone, remove it and re-run bd bootstrap

Example fix

// before
$ bd bootstrap
// error: sync from remote: exec: "dolt": executable file not found in $PATH
// after
$ brew install dolt   # or download from dolthub
$ dolt version && bd bootstrap

// verify dolt CLI availability and remote before bootstrap
if _, err := exec.LookPath("dolt"); err != nil {
	return fmt.Errorf("dolt CLI required for CLI clone mode: %w", err)
}
out, err := exec.Command("dolt", "version").CombinedOutput()
_ = out
_ = err

err := cloneViaCLI(ctx, dir, url, db)
if err != nil && strings.Contains(err.Error(), "sync from remote") {
	// run `dolt clone <url>` manually to see the underlying cause
	// fix PATH/auth/URL, clear a corrupted .beads/dolt, and retry
}

When it happens

Trigger: cloneFromRemoteWithMode falls through to cloneViaCLI (default/owned-server mode, or server mode with no config) and BootstrapFromRemoteWithDB errors: dolt binary not installed or wrong version on PATH, remote URL invalid/unreachable, auth failure, or pre-existing conflicting data directory.

Common situations: dolt CLI not installed (`command not found` wrapped in the error); outdated dolt version incompatible with the remote's storage format; wrong remote URL; corporate proxy blocking doltremoteapi; corrupted existing .beads/dolt directory from an interrupted clone.

Related errors

• database %q not found on Dolt server at %s:%d
• commit import: %w
• create beads directory: %w
• clone from %s succeeded, but the database needs %d schema %s
• write metadata.json: %w

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