gastownhall/beads · error

dolt clone %s: %w

Error message

dolt clone %s: %w

What it means

DoltClone executes CALL DOLT_CLONE(?, ?) to clone a remote Dolt database and wraps failures as 'dolt clone <url>: %w'. The URL is passed through sanitizeURL so credentials (userinfo, query, fragment) are stripped before the error is reported. Failures cover unreachable remotes, bad URLs, authentication failures, or a non-empty target database.

Source

Thrown at internal/storage/versioncontrolops/clone.go:26

// DoltClone clones a Dolt database from a remote URL.
// conn must be a non-transactional database connection.
// The database parameter specifies the local database name for the clone.
// If user is non-empty, authenticates with that user. Dolt reads the remote
// password from DOLT_REMOTE_PASSWORD.
func DoltClone(ctx context.Context, conn DBConn, remoteURL, database, user string) error {
	query := "CALL DOLT_CLONE(?, ?)"
	args := []any{remoteURL, database}
	if user != "" {
		query = "CALL DOLT_CLONE('--user', ?, ?, ?)"
		args = []any{user, remoteURL, database}
	}

	// GH#4272: the initial fetch runs git hooks just like push/pull; disable
	// them for the clone window too (see remotes.go for the full rationale).
	return withRemoteEnvGuards(func() error {
		if _, err := conn.ExecContext(ctx, query, args...); err != nil {
			return fmt.Errorf("dolt clone %s: %w", sanitizeURL(remoteURL), err)
		}
		return nil
	})
}

// sanitizeURL removes credentials from a URL for safe error reporting.
func sanitizeURL(raw string) string {
	parsed, err := url.Parse(raw)
	if err != nil {
		return raw
	}
	parsed.User = nil
	parsed.RawQuery = ""
	parsed.Fragment = ""
	return parsed.String()
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Verify the remote URL is reachable (dolt clone / curl the host) and correctly formed
2. Set DOLT_REMOTE_PASSWORD (and user) in the environment before cloning; for embedded auth use the --user path
3. Ensure the target local database name does not already exist
4. Check the sanitized URL in the error and the wrapped driver error for auth-vs-network distinction

Example fix

// before
err := versioncontrolops.DoltClone(ctx, conn, remoteURL, "cloned", "")
// after
os.Setenv("DOLT_REMOTE_PASSWORD", token) // or pass user and use credentials store
err := versioncontrolops.DoltClone(ctx, conn, remoteURL, "cloned", "myuser")

u, err := url.Parse(remoteURL)
if err != nil || u.Scheme == "" || u.Host == "" {
    return fmt.Errorf("invalid remote URL: %q", remoteURL)
}
if os.Getenv("DOLT_REMOTE_PASSWORD") == "" && needsAuth(u) {
    return fmt.Errorf("DOLT_REMOTE_PASSWORD not set")
}

err := versioncontrolops.DoltClone(ctx, conn, remoteURL, dbName, user)
if err != nil {
    // err message contains sanitized URL; check cause for auth vs network
    log.Printf("clone of %s failed: %v", remoteURL, err)
    return fmt.Errorf("clone failed (check URL, credentials, and target name): %w", err)
}

When it happens

Trigger: Calling DoltClone with an unreachable or misspelled remote URL; missing/incorrect DOLT_REMOTE_PASSWORD or --user credentials; the target local database name already exists; network/firewall blocking the remote; git hooks or env guards interfering during the clone window.

Common situations: CI environments where DOLT_REMOTE_PASSWORD isn't set; cloning over HTTPS from a private remote with expired credentials; firewall/proxy blocking the remote port; re-cloning into an existing database directory.

Related errors

• %w Output: %s
• dolt push failed: %w Output: %s
• dolt clone failed: %w Output: %s Clone target %q already exi
• dolt clone failed: %w Output: %s Cleaned up failed clone tar
• failed to push to peer %s: %w

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