{"record":{"id":"6e7e0896f6165ae3","repo":"gastownhall/beads","slug":"create-beads-directory-w","errorCode":null,"errorMessage":"create beads directory: %w","messagePattern":"create beads directory: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/bootstrap.go","lineNumber":722,"sourceCode":"\tcount, err := importFromLocalJSONL(ctx, s, plan.JSONLFile)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"import from JSONL: %w\", err)\n\t}\n\n\tif err := s.Commit(ctx, \"bd bootstrap: import from issues.jsonl\"); err != nil {\n\t\treturn fmt.Errorf(\"commit import: %w\", err)\n\t}\n\n\tfmt.Fprintf(os.Stderr, \"Imported %d issues from %s\\n\", count, plan.JSONLFile)\n\treturn nil\n}\n\nfunc executeSyncAction(ctx context.Context, plan BootstrapPlan, cfg *configfile.Config) error {\n\t// Ensure .beads directory exists — it may not in the \"fresh clone\"\n\t// bootstrap path where we detected remote data before .beads was\n\t// created. Deferred here to preserve --dry-run semantics. (GH#2792)\n\tif err := os.MkdirAll(plan.BeadsDir, 0o750); err != nil {\n\t\treturn fmt.Errorf(\"create beads directory: %w\", err)\n\t}\n\n\tdbName := cfg.GetDoltDatabase()\n\tif err := cloneFromRemote(ctx, plan.BeadsDir, plan.SyncRemote, dbName, cfg); err != nil {\n\t\treturn err\n\t}\n\n\t// Finalize the bootstrapped workspace so subsequent bd commands can open\n\t// the cloned database. Without metadata.json and config.yaml,\n\t// configfile.Load() returns nil, callers fall back to the default\n\t// dolt_database name, and bd loses track of the cloned database —\n\t// producing \"no beads configuration found\" and \"Error 1105: no database\n\t// selected\" on bd status / bd dolt push in fresh clones. Every other\n\t// bootstrap action (init, restore, jsonl-import) writes these files via\n\t// newDoltStore + createConfigYaml; the sync path historically did not.\n\t// (GH#3201)\n\tif err := finalizeSyncedBootstrap(plan.BeadsDir, plan.SyncRemote, cfg, dbName); err != nil {\n\t\treturn err","sourceCodeStart":704,"sourceCodeEnd":740,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/bootstrap.go#L704-L740","documentation":"`bd bootstrap`'s sync action ensures the `.beads` directory exists before cloning from the remote, because in the fresh-clone path remote data may be detected before `.beads` is created (GH#2792). If `os.MkdirAll` on the configured beads directory fails (permissions, read-only filesystem, path is a file), the error is wrapped as `create beads directory: ...`.","triggerScenarios":"Running `bd bootstrap` where `plan.BeadsDir` (typically `.beads`) cannot be created: parent directory not writable, a regular file named `.beads` exists, read-only mount, or restrictive umask/ownership.","commonSituations":"Bootstrapping inside a read-only CI checkout; `.beads` path colliding with a file; running in a container as a non-root user without volume write permissions.","solutions":["Check that the repo root is writable: `ls -la .beads` — remove the blocking file if `.beads` exists as a regular file.","Fix ownership/permissions: `chown`/`chmod` the repo directory or run in a writable location.","If on a read-only mount (CI artifact checkout), copy the repo to a writable path first.","Verify you are running `bd bootstrap` at the repository root where `.beads` belongs."],"exampleFix":"// before (shell)\n$ touch .beads   # accidentally created a file\n$ bd bootstrap   // create beads directory: mkdir .beads: not a directory\n// after\n$ rm -f .beads\n$ bd bootstrap   # succeeds","handlingStrategy":"validation","validationCode":"# Pre-flight before bd bootstrap:\nBEADS_DIR=.beads\nif [ -e \"$BEADS_DIR\" ] && [ ! -d \"$BEADS_DIR\" ]; then echo \"$BEADS_DIR exists and is not a directory\"; exit 1; fi\n[ -w . ] || { echo \"repo root not writable\"; exit 1; }\nmount | grep -q ' ro,' && echo \"filesystem mounted read-only\"","typeGuard":null,"tryCatchPattern":"if err := executeSyncAction(ctx, plan, cfg); err != nil {\n    if strings.Contains(err.Error(), \"create beads directory:\") {\n        return fmt.Errorf(\"fix .beads path/permissions and re-run bootstrap: %w\", err)\n    }\n    return err\n}","preventionTips":["Never create a file named `.beads`; it shadows the directory.","Run bootstrap in a writable checkout, not a read-only CI mount.","Verify user ownership of the repo before bootstrap (avoid sudo-created dirs).","Check the wrapped mkdir error for EACCES vs ENOTDIR vs ENOSPC."],"tags":["bootstrap","filesystem","permissions"],"backgroundTag":"mkdir-permission-denied","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}