{"record":{"id":"c82ee97bc397104b","repo":"gastownhall/beads","slug":"audit-jsonl-sidecar-is-disabled-set-audit-enabled","errorCode":null,"errorMessage":"audit JSONL sidecar is disabled; set audit.enabled=true or BD_AUDIT_ENABLED=1 to write %s","messagePattern":"audit JSONL sidecar is disabled; set audit\\.enabled=true or BD_AUDIT_ENABLED=1 to write (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"internal/audit/audit.go","lineNumber":160,"sourceCode":"\t// Using bufio.NewWriter could split into multiple write() syscalls,\n\t// which interleave under concurrent O_APPEND and corrupt lines.\n\tvar buf bytes.Buffer\n\tenc := json.NewEncoder(&buf)\n\tenc.SetEscapeHTML(false)\n\tif err := enc.Encode(e); err != nil {\n\t\treturn \"\", fmt.Errorf(\"failed to marshal interactions log entry: %w\", err)\n\t}\n\tif _, err := f.Write(buf.Bytes()); err != nil {\n\t\treturn \"\", fmt.Errorf(\"failed to write interactions log entry: %w\", err)\n\t}\n\n\treturn e.ID, nil\n}\n\n// AppendIfEnabled appends only when the optional JSONL sidecar is enabled.\nfunc AppendIfEnabled(e *Entry) (string, error) {\n\tif !Enabled() {\n\t\treturn \"\", fmt.Errorf(\"audit JSONL sidecar is disabled; set audit.enabled=true or BD_AUDIT_ENABLED=1 to write %s\", FileName)\n\t}\n\treturn Append(e)\n}\n\n// LogFieldChange logs a field change (status, assignee, priority, etc.) to the\n// optional JSONL sidecar when it is enabled. First-class issue history is\n// recorded separately in the database events tables. Best-effort: errors are\n// silently ignored so sidecar logging never blocks operations.\n// Optional reason is included when non-empty (e.g., close reason, cleanup rule).\nfunc LogFieldChange(issueID, field, oldValue, newValue, actor, reason string) {\n\tif oldValue == newValue {\n\t\treturn\n\t}\n\textra := map[string]any{\n\t\t\"field\":     field,\n\t\t\"old_value\": oldValue,\n\t\t\"new_value\": newValue,\n\t}","sourceCodeStart":142,"sourceCodeEnd":178,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/audit/audit.go#L142-L178","documentation":"AppendIfEnabled gates the audit JSONL sidecar on the audit.enabled config key or the BD_AUDIT_ENABLED environment variable; when disabled it returns this descriptive error instead of writing. First-class issue history is always in the database — this sidecar (interactions.jsonl) is opt-in, so the error tells you exactly which switch to flip. Note this means AppendIfEnabled returns an error in the default configuration, which callers must expect.","triggerScenarios":"Calling AppendIfEnabled (directly or via LogFieldChange) in a repo where audit.enabled is unset/false in config and BD_AUDIT_ENABLED is not a truthy value (1/t/true/y/yes/on).","commonSituations":"New installs where the sidecar was never enabled; environments where BD_AUDIT_ENABLED was set only in a shell profile not used by the process; config files loaded from a different directory than expected; users expecting audit logging by default.","solutions":["Set BD_AUDIT_ENABLED=1 in the environment before running the command.","Add audit.enabled = true to the beads config.","Check what Enabled() sees: verify the env var spelling (BD_AUDIT_ENABLED) and truthy spelling (1/true/yes/on).","If the sidecar is intentionally off, treat this error as an expected signal and skip/ignore it in the caller."],"exampleFix":"// before\n_, err := audit.AppendIfEnabled(entry) // disabled by default\n// after\nif audit.Enabled() {\n    if _, err := audit.AppendIfEnabled(entry); err != nil {\n        return fmt.Errorf(\"audit: %w\", err)\n    }\n} // or: export BD_AUDIT_ENABLED=1","handlingStrategy":"type-guard","validationCode":"if !audit.Enabled() {\n    return nil // sidecar intentionally off; skip audit write\n}","typeGuard":"func auditEnabled() bool { return audit.Enabled() }","tryCatchPattern":"if _, err := audit.AppendIfEnabled(e); err != nil {\n    if strings.Contains(err.Error(), \"sidecar is disabled\") {\n        return nil // expected when audit.enabled=false\n    }\n    return err\n}","preventionTips":["Gate all AppendIfEnabled calls behind audit.Enabled().","Export BD_AUDIT_ENABLED=1 in environments where the sidecar is required.","Document that the sidecar is opt-in; don't assume audit writes succeed by default."],"tags":["go","configuration","environment-variable","audit","feature-flag"],"backgroundTag":"feature-disabled","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}