{"record":{"id":"1b25b001dd61641e","repo":"gastownhall/beads","slug":"failed-to-create-dolt-directory-w","errorCode":null,"errorMessage":"failed to create dolt directory: %w","messagePattern":"failed to create dolt directory: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dolt/bootstrap.go","lineNumber":69,"sourceCode":"\t\treturn false, nil\n\t}\n\n\tif err := remotecache.ValidateRemoteURL(remoteURL); err != nil {\n\t\treturn false, fmt.Errorf(\"invalid remote URL: %w\", err)\n\t}\n\n\tif err := ValidateDatabaseName(database); err != nil {\n\t\treturn false, fmt.Errorf(\"invalid database name %q (use cfg.GetDoltDatabase() to resolve the configured name): %w\", database, err)\n\t}\n\n\t// Verify dolt CLI is available\n\tif _, err := exec.LookPath(\"dolt\"); err != nil {\n\t\treturn false, fmt.Errorf(\"dolt CLI not found (required for remote bootstrap): %w\", err)\n\t}\n\n\t// Create the parent dolt directory\n\tif err := os.MkdirAll(doltDir, 0o750); err != nil {\n\t\treturn false, fmt.Errorf(\"failed to create dolt directory: %w\", err)\n\t}\n\n\t// Clone into <doltDir>/<database>/ so the embedded driver can find it.\n\t// `dolt clone <url> <target>` creates <target>/.dolt/ directly.\n\tcloneTarget := filepath.Join(doltDir, database)\n\t// Record whether the target already existed before this clone attempt.\n\t// If it did, the failed-clone cleanup below must never touch it: it\n\t// wasn't created by us, so it could be a pre-existing Dolt repo (e.g.\n\t// from an earlier bootstrap that a stale/empty doltExists() check\n\t// missed) that we must not delete.\n\ttargetPreExisted := pathExists(cloneTarget)\n\tcmd := bootstrapCloneCmd(ctx, remoteURL, cloneTarget)\n\tif output, err := cmd.CombinedOutput(); err != nil {\n\t\tif targetPreExisted {\n\t\t\treturn 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)\n\t\t}\n\t\tcleaned, cleanupErr := removeFailedCloneTargetWithRetry(cloneTarget)\n\t\treturn false, formatFailedCloneTargetError(err, output, cloneTarget, cleaned, cleanupErr)","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dolt/bootstrap.go#L51-L87","documentation":"After validating inputs and the dolt CLI, bootstrap creates the parent .beads/dolt directory with os.MkdirAll(doltDir, 0o750). This error wraps any failure from that creation — typically a permissions problem on an ancestor directory, a read-only filesystem, or a non-directory file occupying part of the path.","triggerScenarios":"BootstrapFromRemoteWithDB calls os.MkdirAll on the dolt directory and it fails: parent dir not writable by the current user, path component is a regular file, disk full, read-only mount, or SELinux/AppArmor denial.","commonSituations":".beads owned by another user after running bd with sudo once; cloning a repo where .beads contains a committed stub file named \"dolt\"; running in a read-only container rootfs; NFS/locked-down corporate mounts denying creation with mode 0o750.","solutions":["Check ownership/permissions on the .beads directory and its parents (`ls -la .beads`) and fix with chown/chmod so the running user can create subdirectories.","If a file named `dolt` exists at the target path, remove or rename it (`rm .beads/dolt` if it is a stray file, after confirming it is not a symlink you need).","Verify the filesystem is writable (`touch .beads/test`) — remount read-only volumes or move the workspace to a writable location.","If SELinux/AppArmor denied the operation, check audit logs and adjust policy, or run in a context that permits writes to the workspace.","Check disk space with `df -h .` and free space if the disk is full."],"exampleFix":"# before\n$ sudo bd doctor   # .beads/dolt created as root\n$ bd bootstrap     # failed to create dolt directory: permission denied\n# after\n$ sudo chown -R \"$USER\" .beads\n$ bd bootstrap","handlingStrategy":"validation","validationCode":"if err := os.MkdirAll(doltDir, 0o750); err != nil {\n    return fmt.Errorf(\"cannot write %s: %w\", doltDir, err)\n}","typeGuard":null,"tryCatchPattern":"ok, err := dolt.BootstrapFromRemote(ctx, doltDir, remote)\nif err != nil && strings.Contains(err.Error(), \"failed to create dolt directory\") {\n    // check ownership/permissions of .beads and its parents before retrying\n}","preventionTips":["Never run bd under sudo in a workspace owned by your user; fix ownership with chown if it happened.","Keep .beads on a writable local filesystem, not read-only mounts or network shares.","Ensure nothing in the repo commits a regular file at .beads/dolt."],"tags":["filesystem","permissions","dolt","bootstrap"],"backgroundTag":"permission-denied","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}