{"record":{"id":"c583ff11d6511a12","repo":"gastownhall/beads","slug":"no-beads-directory-found","errorCode":null,"errorMessage":"no .beads directory found","messagePattern":"no \\.beads directory found","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/audit/audit.go","lineNumber":59,"sourceCode":"\tResponse string `json:\"response,omitempty\"`\n\tError    string `json:\"error,omitempty\"`\n\n\t// Tool call\n\tToolName string `json:\"tool_name,omitempty\"`\n\tExitCode *int   `json:\"exit_code,omitempty\"`\n\n\t// Labeling (append-only)\n\tParentID string `json:\"parent_id,omitempty\"`\n\tLabel    string `json:\"label,omitempty\"`  // \"good\" | \"bad\" | etc\n\tReason   string `json:\"reason,omitempty\"` // human / pipeline explanation\n\n\tExtra map[string]any `json:\"extra,omitempty\"`\n}\n\nfunc Path() (string, error) {\n\tbeadsDir := beads.FindBeadsDir()\n\tif beadsDir == \"\" {\n\t\treturn \"\", fmt.Errorf(\"no .beads directory found\")\n\t}\n\treturn filepath.Join(beadsDir, FileName), nil\n}\n\n// Enabled reports whether the optional JSONL interaction sidecar is enabled.\n// First-class issue history is always recorded in the database events tables;\n// this gate only controls .beads/interactions.jsonl.\nfunc Enabled() bool {\n\tif raw, ok := os.LookupEnv(\"BD_AUDIT_ENABLED\"); ok {\n\t\treturn truthy(raw)\n\t}\n\treturn config.GetBool(\"audit.enabled\")\n}\n\nfunc truthy(raw string) bool {\n\tswitch strings.ToLower(strings.TrimSpace(raw)) {\n\tcase \"1\", \"t\", \"true\", \"y\", \"yes\", \"on\":\n\t\treturn true","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/audit/audit.go#L41-L77","documentation":"audit.Path locates the current .beads directory via beads.FindBeadsDir(). If no .beads directory can be found (not in a beads repository and none in any parent), it returns this error because the JSONL interactions sidecar has nowhere to live.","triggerScenarios":"Calling audit.Path(), audit.EnsureFile(), or audit.Append() outside any directory containing .beads (and with no .beads in ancestors), or when BD_DIR/discovery state is missing.","commonSituations":"Running bd from a scratch/temp directory, HOME misconfigured so the default beads location isn't found, or running before ever running `bd init` in the project.","solutions":["Run `bd init` (or create the .beads directory) in your project root before relying on audit features","Run the command from inside the beads repository (or a subdirectory of it)","Set the beads directory explicitly if your environment supports it (e.g. BD_DIR) instead of relying on upward discovery"],"exampleFix":"// before\ncd /tmp && bd doctor   // no .beads anywhere up the tree\n// after\ncd /path/to/project && bd init && bd doctor","handlingStrategy":"validation","validationCode":"dir := beads.FindBeadsDir()\nif dir == \"\" {\n    return fmt.Errorf(\"not inside a beads repo: run 'bd init' first\")\n}","typeGuard":null,"tryCatchPattern":"p, err := audit.Path()\nif err != nil {\n    if err.Error() == \"no .beads directory found\" {\n        return fmt.Errorf(\"run 'bd init' in your project before using audit features\")\n    }\n    return err\n}","preventionTips":["Run `bd init` before scripting against bd from a fresh checkout or CI job","Invoke bd from within the project (or a subdirectory), not from $HOME or /tmp","Verify FindBeadsDir() in setup scripts as a preflight check"],"tags":["beads","configuration","filesystem"],"backgroundTag":"missing-beads-directory","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}