{"record":{"id":"bc10a6885be71901","repo":"gastownhall/beads","slug":"dolt-clone-failed-w-output-s-could-not-clean-u","errorCode":null,"errorMessage":"dolt clone failed: %w\nOutput: %s\nCould not clean up failed clone target %q after retrying: %v\nOn Windows this usually means a dolt or bd process, or antivirus scanner, still has a file handle open under `.dolt/noms/LOCK`. Stop stuck dolt/bd processes, wait a moment, delete the directory manually if it remains, then retry `bd bootstrap`","messagePattern":"dolt clone failed: %w\nOutput: (.+?)\nCould not clean up failed clone target %q after retrying: (.+?)\nOn Windows this usually means a dolt or bd process, or antivirus scanner, still has a file handle open under `\\.dolt/noms/LOCK`\\. Stop stuck dolt/bd processes, wait a moment, delete the directory manually if it remains, then retry `bd bootstrap`","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dolt/bootstrap.go","lineNumber":144,"sourceCode":"\t\t}\n\t\tif attempt >= len(failedCloneCleanupRetryDelays) {\n\t\t\treturn true, err\n\t\t}\n\t\ttime.Sleep(failedCloneCleanupRetryDelays[attempt])\n\t}\n}\n\nfunc formatFailedCloneTargetError(cloneErr error, output []byte, cloneTarget string, cleaned bool, cleanupErr error) error {\n\tif cleanupErr == nil && cleaned {\n\t\treturn fmt.Errorf(\"dolt clone failed: %w\\nOutput: %s\\nCleaned up failed clone target %q; fix the clone error above and retry `bd bootstrap`\", cloneErr, output, cloneTarget)\n\t}\n\tif cleanupErr == nil {\n\t\treturn fmt.Errorf(\"dolt clone failed: %w\\nOutput: %s\", cloneErr, output)\n\t}\n\tif !cleaned {\n\t\treturn fmt.Errorf(\"dolt clone failed: %w\\nOutput: %s\\nCould not inspect failed clone target %q before cleanup: %v\\nOn Windows this usually means a dolt or bd process, or antivirus scanner, still has a file handle open under `.dolt/noms/LOCK`. Stop stuck dolt/bd processes, wait a moment, delete the directory manually if it remains, then retry `bd bootstrap`\", cloneErr, output, cloneTarget, cleanupErr)\n\t}\n\treturn fmt.Errorf(\"dolt clone failed: %w\\nOutput: %s\\nCould not clean up failed clone target %q after retrying: %v\\nOn Windows this usually means a dolt or bd process, or antivirus scanner, still has a file handle open under `.dolt/noms/LOCK`. Stop stuck dolt/bd processes, wait a moment, delete the directory manually if it remains, then retry `bd bootstrap`\", cloneErr, output, cloneTarget, cleanupErr)\n}\n\nfunc doltCloneArgs(remoteURL, target string) []string {\n\targs := []string{\"clone\"}\n\tif user := os.Getenv(\"DOLT_REMOTE_USER\"); user != \"\" {\n\t\targs = append(args, \"--user\", user)\n\t}\n\treturn append(args, remoteURL, target)\n}\n\n// BootstrapFromGitRemoteWithDB is deprecated. Use BootstrapFromRemoteWithDB instead.\nfunc BootstrapFromGitRemoteWithDB(ctx context.Context, doltDir, gitRemoteURL, database string) (bool, error) {\n\treturn BootstrapFromRemoteWithDB(ctx, doltDir, gitRemoteURL, database)\n}\n\n// pathExists reports whether path exists (of any type), without following\n// symlinks. Used to detect whether a clone target pre-existed before a\n// clone attempt, so failed-clone cleanup never deletes something it didn't","sourceCodeStart":126,"sourceCodeEnd":162,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dolt/bootstrap.go#L126-L162","documentation":"This error wraps a failure of the underlying `dolt clone` command during `bd bootstrap` (cloning a remote Dolt database), and additionally reports that the partially-created clone target directory could not be deleted during cleanup. It appears only when both the clone failed AND a post-failure cleanup retry of os.RemoveAll failed. On Windows this is almost always a file-handle/locking issue on files under the clone directory (e.g. `.dolt/noms/LOCK`).","triggerScenarios":"BootstrapFromRemoteWithDB calls dolt clone; the clone itself errors (bad remote URL, auth failure, network down, corrupt remote), then the code tries to remove the leftover target directory and that removal fails, typically because a dolt/bd process or antivirus scanner holds an open handle to a file under the directory.","commonSituations":"Stale dolt server processes from a previous crashed bootstrap; Windows Defender or another AV scanner scanning freshly written `.dolt/noms` files during cleanup; the target directory being open in Explorer, a shell, or an editor; insufficient permissions on the target path.","solutions":["Stop any running dolt/bd processes (task manager / `taskkill` or `pkill dolt`), then retry `bd bootstrap`","On Windows, wait a few seconds for the AV scanner to release handles, then delete the target directory manually and retry `bd bootstrap`","Inspect the wrapped clone error and `Output:` section for the root cause of the clone itself (auth, URL, network) and fix that before retrying","Reboot or close any programs (Explorer, editors) holding the directory open, then retry"],"exampleFix":"// before (manual recovery)\nrm -rf ./path/to/failed-clone-target\nbd bootstrap\n// after (ensure no lingering processes first)\npkill dolt; pkill bd\nrm -rf ./path/to/failed-clone-target\nbd bootstrap","handlingStrategy":"try-catch","validationCode":"// before bootstrap: ensure no clone target exists and no stale handles\nif _, err := os.Stat(target); err == nil {\n    if err := os.RemoveAll(target); err != nil {\n        // another process/AV holds handles; stop dolt/bd processes first\n    }\n}","typeGuard":null,"tryCatchPattern":"var bootErr *os.PathError\nif err := bd.BootstrapFromRemoteWithDB(ctx, url, target); err != nil {\n    if strings.Contains(err.Error(), \"Could not clean up failed clone target\") {\n        // stop dolt/bd processes, wait, manually os.RemoveAll(target), retry once\n    } else if errors.As(err, &bootErr) {\n        // fix path-level clone problem reported in Output:\n    }\n}","preventionTips":["Ensure no dolt/bd processes are running before re-running bootstrap","Exclude the project directory from antivirus real-time scanning (Windows Defender exclusions)","Remove stale clone target directories before retrying bootstrap","On Windows, close Explorer windows/editors open inside the target directory"],"tags":["dolt","windows","file-locked","clone","bootstrap"],"backgroundTag":"file-handle-locked-on-windows","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}