{"record":{"id":"6fed693af9e734b3","repo":"gastownhall/beads","slug":"failed-to-create-beads-directory-s-w","errorCode":null,"errorMessage":"failed to create beads directory %s: %w","messagePattern":"failed to create beads directory (.+?): %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dolt/credentials.go","lineNumber":100,"sourceCode":"\t\t}\n\t}\n\n\t// Generate new random 32-byte key (AES-256)\n\tkey = make([]byte, 32)\n\tif _, err := io.ReadFull(rand.Reader, key); err != nil {\n\t\treturn fmt.Errorf(\"failed to generate credential encryption key: %w\", err)\n\t}\n\n\t// Migrate existing credentials from old dbPath-derived key to new random key\n\tif err := s.migrateCredentialKeys(ctx, key); err != nil {\n\t\treturn fmt.Errorf(\"failed to migrate credential keys: %w\", err)\n\t}\n\n\t// Write key file with owner-only permissions (0600).\n\t// Ensure the directory exists first — when connecting to an external\n\t// server without having run `bd init`, .beads/ may not exist yet (GH#2641).\n\tif err := os.MkdirAll(s.beadsDir, 0700); err != nil {\n\t\treturn fmt.Errorf(\"failed to create beads directory %s: %w\", s.beadsDir, err)\n\t}\n\tif err := os.WriteFile(keyPath, key, 0600); err != nil {\n\t\treturn fmt.Errorf(\"failed to write credential key file: %w\", err)\n\t}\n\n\ts.credentialKey = key\n\treturn nil\n}\n\n// ensureCredentialKey lazily initializes the credential key when federation\n// operations actually need password encryption or decryption.\nfunc (s *DoltStore) ensureCredentialKey(ctx context.Context) error {\n\ts.mu.RLock()\n\tif s.credentialKey != nil {\n\t\ts.mu.RUnlock()\n\t\treturn nil\n\t}\n\ts.mu.RUnlock()","sourceCodeStart":82,"sourceCodeEnd":118,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dolt/credentials.go#L82-L118","documentation":"Before writing the credential key file, initCredentialKey ensures the .beads directory exists via os.MkdirAll(s.beadsDir, 0700). This error wraps a failure of that directory creation, meaning bd could not create the directory that must hold the encryption key. It commonly surfaces when connecting to an external server without having run `bd init` (GH#2641) and the parent path is not creatable.","triggerScenarios":"os.MkdirAll(s.beadsDir, 0700) fails during initCredentialKey: the .beads directory (or an ancestor) cannot be created because a parent is missing on a read-only filesystem, permission is denied, the path exists as a regular file, or the workspace root is on a read-only mount.","commonSituations":"Connecting to an external dolt-sql-server from a directory where .beads/ was never initialized and the cwd is read-only or unwritable; a file named .beads exists where the directory should be; running as a different user than the workspace owner; container images with read-only workdirs.","solutions":["Check that the directory at the reported path can be created: verify write permission on its parent (ls -ld <parent>)","If a regular file named .beads exists, remove or rename it so the directory can be created","Create the directory manually: mkdir -p .beads (or run `bd init` first)","If the workspace is intentionally read-only, run bd from a writable workspace or point it at a writable location"],"exampleFix":"// before\n$ bd sync  # fails: failed to create beads directory /ro-workspace/.beads: mkdir ...: read-only file system\n// after\n$ chmod u+w /ro-workspace && bd init   # or: mkdir -p /ro-workspace/.beads","handlingStrategy":"validation","validationCode":"beadsDir := \".beads\"\nif info, err := os.Stat(beadsDir); err == nil && !info.IsDir() {\n    return fmt.Errorf(\"%s exists as a file; remove it so the directory can be created\", beadsDir)\n}\nif err := os.MkdirAll(beadsDir, 0700); err != nil { return err }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run `bd init` before connecting to external servers (GH#2641 scenario)","Never place a file named .beads in a workspace","Run bd as a user with write access to the workspace root","Keep workspaces on writable mounts"],"tags":["filesystem","permissions","directory-creation"],"backgroundTag":"mkdir-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}