gastownhall/beads · error

clone from remote: %w

Error message

clone from remote: %w

What it means

Wrapped by cloneViaEmbedded in cmd/bd/bootstrap.go:937 when versioncontrolops.DoltClone fails to run CALL DOLT_CLONE against the remote URL using the embedded SQL engine. The engine started fine; the actual remote clone (network, auth, or remote existence) failed.

Source

Thrown at cmd/bd/bootstrap.go:937

	default:
		return remoteCloneCLI
	}
}

// cloneViaEmbedded clones using the embedded Dolt engine (CGO required).
func cloneViaEmbedded(ctx context.Context, beadsDir, remoteURL, dbName string) error {
	dataDir := filepath.Join(beadsDir, "embeddeddolt")
	if err := os.MkdirAll(dataDir, 0o750); err != nil {
		return fmt.Errorf("create embeddeddolt directory: %w", err)
	}
	db, cleanup, err := embeddeddolt.OpenSQL(ctx, dataDir, "", "")
	if err != nil {
		return fmt.Errorf("open embedded engine for clone: %w", err)
	}
	defer func() { _ = cleanup() }()

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

// 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(),

View on GitHub (pinned to 71377f2769)

Solutions

1. Verify the remote URL (dolt ls-commits or curl it / try `dolt clone <url>` manually with the dolt CLI)
2. Set correct credentials: export DOLT_REMOTE_USER and ensure ~/.dolt credentials match the remote account
3. Confirm the remote database/org name exists and your user has read access
4. Check network/proxy access to doltremoteapi.dolthub.com and retry (clone is safe to re-run)

Example fix

// before: no credentials for private remote
$ bd bootstrap
// error: clone from remote: unable to authenticate
// after
$ dolt config --global --add user.email you@example.com
$ export DOLT_REMOTE_USER=you
$ dolt clone https://doltremoteapi.dolthub.com/org/beads  # verify access
$ bd bootstrap

// verify remote reachability before clone
url := "https://doltremoteapi.dolthub.com/org/beads"
resp, err := http.Head(url)
if err != nil || resp.StatusCode >= 500 { /* fix network/auth first */ }
if os.Getenv("DOLT_REMOTE_USER") == "" { /* set credentials for private remotes */ }

err := cloneViaEmbedded(ctx, dir, remoteURL, dbName)
if err != nil && strings.Contains(err.Error(), "clone from remote") {
	// check credentials/network, then retry — clone is idempotent on failure
	time.Sleep(2 * time.Second)
	err = cloneViaEmbedded(ctx, dir, remoteURL, dbName)
}

When it happens

Trigger: DoltClone(ctx, db, remoteURL, dbName, DOLT_REMOTE_USER) returns an error: remote URL unreachable/DNS failure, authentication rejected (bad DOLT_REMOTE_USER / credentials), remote database does not exist, or the clone timed out on a large database.

Common situations: Wrong remote URL typed into bd init --remote; expired or missing Dolt remote credentials; private repo without auth; corporate proxy blocking doltremoteapi.dolthub.com; transient network drop.

Related errors

• failed to fetch teams: %w
• dolt push failed: %w Output: %s
• %w Output: %s
• dolt clone %s: %w
• fetch from %s: %w

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