gastownhall/beads · error

dolt clone failed: %w Output: %s Clone target %q already exi

Error message

dolt clone failed: %w
Output: %s
Clone target %q already existed before this attempt; left untouched to avoid deleting a pre-existing Dolt repo

What it means

When `dolt clone <remote> <target>` fails and the clone target directory already existed before the attempt, bootstrap deliberately does NOT delete it — it might be a pre-existing Dolt repo that a stale doltExists() check missed. Instead it reports the clone failure plus the raw dolt output and notes the pre-existing target was left untouched. This is the safety-preserving branch of the clone error path.

Source

Thrown at internal/storage/dolt/bootstrap.go:84

	// Create the parent dolt directory
	if err := os.MkdirAll(doltDir, 0o750); err != nil {
		return false, fmt.Errorf("failed to create dolt directory: %w", err)
	}

	// Clone into <doltDir>/<database>/ so the embedded driver can find it.
	// `dolt clone <url> <target>` creates <target>/.dolt/ directly.
	cloneTarget := filepath.Join(doltDir, database)
	// Record whether the target already existed before this clone attempt.
	// If it did, the failed-clone cleanup below must never touch it: it
	// wasn't created by us, so it could be a pre-existing Dolt repo (e.g.
	// from an earlier bootstrap that a stale/empty doltExists() check
	// missed) that we must not delete.
	targetPreExisted := pathExists(cloneTarget)
	cmd := bootstrapCloneCmd(ctx, remoteURL, cloneTarget)
	if output, err := cmd.CombinedOutput(); err != nil {
		if targetPreExisted {
			return false, fmt.Errorf("dolt clone failed: %w\nOutput: %s\nClone target %q already existed before this attempt; left untouched to avoid deleting a pre-existing Dolt repo", err, output, cloneTarget)
		}
		cleaned, cleanupErr := removeFailedCloneTargetWithRetry(cloneTarget)
		return false, formatFailedCloneTargetError(err, output, cloneTarget, cleaned, cleanupErr)
	}

	fmt.Fprintf(os.Stderr, "Bootstrapped from remote: %s\n", remoteURL)
	return true, nil
}

// bootstrapCloneCmd builds the `dolt clone` for remote bootstrap. It does not
// route through prepareDoltCLITransferCommand, so it applies the remote env
// guards itself (see internal/gittraceenv and internal/githooksenv).
func bootstrapCloneCmd(ctx context.Context, remoteURL, cloneTarget string) *exec.Cmd {
	cmd := exec.CommandContext(ctx, "dolt", doltCloneArgs(remoteURL, cloneTarget)...)
	cmd.Env = githooksenv.DisabledEnv(gittraceenv.ScrubEnv(os.Environ()))
	return cmd
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Read the Output section of the error: it contains dolt's own failure reason (auth failure, unknown remote, network error) and fix that underlying cause first.
2. Inspect the target directory (`ls -la .beads/dolt/<db>`); if it is leftover debris and not a valid Dolt repo, remove it manually and retry `bd bootstrap`.
3. If it is a valid pre-existing repo you want to keep, skip bootstrap — point the embedded driver at it or run `bd dolt pull` inside it instead of cloning.
4. For auth failures, set DOLT_REMOTE_USER or configure dolt credentials (`dolt login`) so the clone can succeed.
5. Verify network/VPN access to the remote (DoltHub, S3, GCS, git host) and retry.

Example fix

# before: stale partial clone blocks bootstrap
$ ls .beads/dolt/beads      # leftover junk, no .dolt
$ bd bootstrap              # clone failed... target already existed
# after: confirm it's not a real repo, then remove it
$ rm -rf .beads/dolt/beads
$ bd bootstrap

if target := filepath.Join(doltDir, db); pathExists(target) && !hasDoltDir(target) {
    // stale partial clone: remove it or resolve it before bootstrapping
}

ok, err := dolt.BootstrapFromRemote(ctx, doltDir, remote)
if err != nil && strings.Contains(err.Error(), "already existed before this attempt") {
    // inspect the target: clean it manually if debris, or adopt it via `bd dolt pull`
}

When it happens

Trigger: BootstrapFromRemoteWithDB runs `dolt clone` into <doltDir>/<database> and the command exits non-zero, while pathExists(cloneTarget) was true before the run — e.g. a partially-populated or non-Dolt directory sits at the target, or doltExists() returned false because no .dolt subdirectory was present yet.

Common situations: A previous bootstrap crashed leaving an incomplete clone without .dolt at a detectable level; the target path was created by something else (git checkout of files under .beads/dolt/beads); the remote requires auth so clone fails while a stale directory blocks retry.

Related errors

• dolt clone failed: %w Output: %s Cleaned up failed clone tar
• %w Output: %s
• dolt clone failed: %w Output: %s
• dolt clone failed: %w Output: %s Could not inspect failed cl
• dolt clone failed: %w Output: %s Could not clean up failed c

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