Port the website's current (non-versioned) authored pages into docs/ as
Mintlify pages: frontmatter title as H1 (body H1s removed), Docusaurus
admonitions converted to Mintlify components, root-relative extensionless
links, mermaid fences kept as-is. website/docs/** is untouched and keeps
serving the Docusaurus site until cutover.
git-mv the user-facing docs/ originals with no website twin into the new
IA (core-concepts/, architecture/, workflows/, recovery/, multi-agent/,
integrations/, reference/), converted to Mintlify form. The six files
previously mirrored by sync-website-docs.sh now live once in the site.
ERROR_HANDLING.md and CONTRIBUTOR_NAMESPACE_ISOLATION.md move to engdocs/
(contributor pattern guide and design doc per content review).
Pointer stubs remain at docs/{DOLT,STORAGE-BACKENDS,PLUGIN,RECOVERY,
JSON_SCHEMA}.md because released bd binaries print those paths; QUICKSTART
and DOLT-BACKEND stay as existing pointer stubs.
Corrected while porting: the intro's storage diagram claimed data lives at
.beads/dolt/; embedded mode (the default) uses .beads/embeddeddolt/
(internal/storage/embeddeddolt/store.go), server mode uses .beads/dolt/.
14 KiB
Error Handling Guidelines
Last reviewed: 2026-07-07
Freshness source: cmd/bd/*.go, especially command error exits and JSON error
helpers in cmd/bd/errors.go.
This document describes the error handling patterns used throughout the beads codebase and provides guidelines for when each pattern should be applied.
Overview
The beads codebase currently uses three distinct error handling patterns across different scenarios. Understanding when to use each pattern is critical for maintaining consistent behavior and a good user experience.
The Three Patterns
Pattern A: Return a Fatal Error Through RunE (return HandleError(...))
When to use:
- Fatal errors that prevent the command from completing its core function
- User input validation failures (invalid flags, malformed arguments)
- Critical preconditions not met (missing database, corrupted state)
- Unrecoverable system errors (filesystem failures, permission denied)
Example:
if err := store.CreateIssue(ctx, issue, actor); err != nil {
return HandleError("%v", err)
}
Why not os.Exit(1)? Calling os.Exit inside a command handler abandons the
stack without running deferred functions — the per-command metrics event
(CloseEventAndAdd) and main()'s metrics.CloseAndFlush() never run, so the
invocation records no usage event and any deferred cleanup (unit-of-work close,
temp-file removal) is skipped. Instead return a HandleError* value: it prints
the message and returns a sentinel *exitError; cobra unwinds the stack (running
every defer), and main() maps the sentinel to exit code 1.
Characteristics:
- Prints
Error:(plusHint:for theWithHintvariants) to stderr; theRespectJSONvariants emit a structured JSON error to stdout under--json - Returns
&exitError{Code: 1}up throughRunE;main()exits 1 after deferred cleanup and the metrics flush have run - The command's
cobra.Commandmust setSilenceUsage: trueandSilenceErrors: true, or cobra will additionally printError: exit code 1and the usage text on top of the real message
Narrow exceptions still using os.Exit: process-level gates that run before
or outside the RunE error path — e.g. CheckReadonly, which aborts a blocked
command after flushing metrics first. A handful of pre-existing direct
os.Exit(1) calls also remain inside handler bodies; new command code should
return a HandleError* value instead of adding more.
Files using this pattern: nearly every command in cmd/bd/ — search for
return HandleError (e.g. create.go, defer.go, dolt.go, unclaim.go,
compact.go).
Pattern B: Warn and Continue (fmt.Fprintf + continue)
When to use:
- Optional operations that enhance functionality but aren't required
- Metadata operations (config updates, analytics, logging)
- Cleanup operations (removing temp files, closing resources)
- Auxiliary features (git hooks installation, merge driver setup)
Example:
if err := createConfigYaml(beadsDir, false); err != nil {
fmt.Fprintf(os.Stderr, "Warning: failed to create config.yaml: %v\n", err)
// Non-fatal - continue anyway
}
Characteristics:
- Writes
Warning:prefix to stderr - Includes context about what failed
- Command continues execution
- Core functionality still works
Files using this pattern:
cmd/bd/init.go(lines 155-157, 161-163, 167-169, 188-190, 236-238, 272-274, etc.)cmd/bd/sync.go(lines 156, 257, 281, 329, 335, 720-722, 740, 743, 752, 762)cmd/bd/create.go(lines 333-334, 340-341)cmd/bd/sync.go(handles Dolt sync operations)
Pattern C: Silent Ignore (_ = operation())
When to use:
- Resource cleanup where failure doesn't matter (closing files, removing temps)
- Idempotent operations in error paths (already logging primary error)
- Best-effort operations with no user-visible impact
Example:
_ = store.Close()
_ = os.Remove(tempPath)
Characteristics:
- No output to user
- Typically in
deferstatements or error paths - Operation failure has no material impact
- Primary error already reported
Files using this pattern:
cmd/bd/init.go(line 209, 326-327)cmd/bd/sync.go(lines 696-698)cmd/bd/sync.go(sync cleanup)- Dozens of other locations throughout the codebase
Decision Tree
Use this flowchart to choose the appropriate error handling pattern:
┌─────────────────────────────────────┐
│ Did an error occur? │
└─────────────┬───────────────────────┘
│
├─ NO → Continue normally
│
└─ YES → Ask:
│
├─ Is this a fatal error that prevents
│ the command's core purpose?
│
│ YES → Pattern A: return HandleError(...) from RunE
│ • Prints "Error: ..." to stderr
│ • Provide actionable hint (HandleErrorWithHint)
│ • Returns *exitError; main() exits 1 after defers
│
├─ Is this an optional/auxiliary operation
│ where the command can still succeed?
│
│ YES → Pattern B: Warn and continue
│ • Write "Warning: ..." to stderr
│ • Explain what failed
│ • Continue execution
│
└─ Is this a cleanup/best-effort operation
where failure doesn't matter?
YES → Pattern C: Silent ignore
• Use _ = operation()
• No user output
• Typically in defer/error paths
Examples by Scenario
User Input Validation → Pattern A (Return Fatal Error)
priority, err := validation.ValidatePriority(priorityStr)
if err != nil {
return HandleError("%v", err)
}
Creating Auxiliary Config Files → Pattern B (Warn)
if err := createConfigYaml(localBeadsDir, false); err != nil {
fmt.Fprintf(os.Stderr, "Warning: failed to create config.yaml: %v\n", err)
// Non-fatal - continue anyway
}
Cleanup Operations → Pattern C (Ignore)
defer func() {
_ = tempFile.Close()
if writeErr != nil {
_ = os.Remove(tempPath)
}
}()
Optional Metadata Updates → Pattern B (Warn)
if err := store.SetMetadata(ctx, "last_import_hash", currentHash); err != nil {
fmt.Fprintf(os.Stderr, "Warning: failed to update last_import_hash: %v\n", err)
}
Database Transaction Failures → Pattern A (Return Fatal Error)
if err := store.CreateIssue(ctx, issue, actor); err != nil {
return HandleError("%v", err)
}
Anti-Patterns to Avoid
❌ Don't mix patterns inconsistently
// BAD: Same type of operation handled differently
if err := createConfigYaml(dir, false); err != nil {
fmt.Fprintf(os.Stderr, "Warning: %v\n", err) // Warns
}
if err := createReadme(dir); err != nil {
fmt.Fprintf(os.Stderr, "Error: %v\n", err)
os.Exit(1) // Exits - inconsistent!
}
// GOOD: Consistent pattern for similar operations
if err := createConfigYaml(dir, false); err != nil {
fmt.Fprintf(os.Stderr, "Warning: failed to create config.yaml: %v\n", err)
}
if err := createReadme(dir); err != nil {
fmt.Fprintf(os.Stderr, "Warning: failed to create README.md: %v\n", err)
}
❌ Don't silently ignore critical errors
// BAD: Critical operation ignored
_ = store.CreateIssue(ctx, issue, actor)
// GOOD: Return a fatal error through RunE
if err := store.CreateIssue(ctx, issue, actor); err != nil {
return HandleError("%v", err)
}
❌ Don't exit on auxiliary operations
// BAD: Exiting when git hooks fail is too aggressive
if err := installGitHooks(); err != nil {
fmt.Fprintf(os.Stderr, "Error: %v\n", err)
os.Exit(1)
}
// GOOD: Warn and suggest fix
if err := installGitHooks(); err != nil {
yellow := color.New(color.FgYellow).SprintFunc()
fmt.Fprintf(os.Stderr, "\n%s Failed to install git hooks: %v\n", yellow("⚠"), err)
fmt.Fprintf(os.Stderr, "You can try again with: %s\n\n", cyan("bd doctor --fix"))
}
Testing Considerations
When writing tests for error handling:
- Pattern A (Fatal) - Assert
RunEreturns a non-nil error (a*exitError); no subprocess oros.Exitmock needed, sinceHandleErrorreturns rather than exiting - Pattern B (Warn) - Capture stderr and verify warning message
- Pattern C (Ignore) - Verify operation was attempted, no error propagates
Common Pitfalls
Metadata Operations
IMPORTANT: Not all metadata is created equal. There are two distinct categories with different error handling requirements:
Configuration Metadata (Pattern A: Fatal)
Configuration metadata defines fundamental system behavior and must succeed:
// Pattern A: return a fatal error through RunE.
// Returning lets a single `defer store.Close()` cover every exit path, instead
// of repeating a manual `_ = store.Close()` before each os.Exit (which os.Exit
// would otherwise skip).
defer store.Close()
if err := store.SetConfig(ctx, "issue_prefix", prefix); err != nil {
return HandleError("failed to set issue prefix: %v", err)
}
if err := syncbranch.Set(ctx, store, branch); err != nil {
return HandleError("failed to set sync branch: %v", err)
}
Examples:
issue_prefix- Defines how all issue IDs are generatedsync.branch- Critical for git synchronization workflow
Rationale: These settings are prerequisites for basic operation. Without them, the system cannot function correctly. A failure here indicates a serious problem (e.g., filesystem issues, database corruption).
Tracking Metadata (Pattern B: Warn and Continue)
Tracking metadata enhances functionality but the system works without it:
// Pattern B: Warn and continue
if err := store.SetMetadata(ctx, "bd_version", Version); err != nil {
fmt.Fprintf(os.Stderr, "Warning: failed to store version metadata: %v\n", err)
// Non-fatal - continue anyway
}
if err := store.SetMetadata(ctx, "repo_id", repoID); err != nil {
fmt.Fprintf(os.Stderr, "Warning: failed to set repo_id: %v\n", err)
}
if err := store.SetMetadata(ctx, "last_import_hash", hash); err != nil {
fmt.Fprintf(os.Stderr, "Warning: failed to update last_import_hash: %v\n", err)
}
Examples:
bd_version- Enables version mismatch warnings on upgradesrepo_id/clone_id- Helps with collision detection across cloneslast_import_hash- Optimizes staleness detection (falls back to mtime if unavailable)
Rationale: System degrades gracefully if tracking metadata is unavailable. Core functionality (creating issues, importing data) still works. Failures here might indicate temporary issues (e.g., read-only filesystem) that shouldn't block the entire operation.
See also: cmd/bd/init.go lines 206-272 for detailed inline documentation of this distinction.
File Permission Errors
Setting file permissions is typically Pattern B because the file was already written:
if err := os.Chmod(jsonlPath, 0600); err != nil {
fmt.Fprintf(os.Stderr, "Warning: failed to set file permissions: %v\n", err)
}
Resource Cleanup
Always use Pattern C for cleanup in error paths:
defer func() {
_ = tempFile.Close() // Pattern C: already handling primary error
if writeErr != nil {
_ = os.Remove(tempPath) // Pattern C: best effort cleanup
}
}()
Enforcement Strategy
Code Review Checklist
- Fatal errors use Pattern A with descriptive error message
- Optional operations use Pattern B with "Warning:" prefix
- Cleanup operations use Pattern C (silent)
- Similar operations use consistent patterns
- Error messages provide actionable hints when possible
Error Helpers
cmd/bd/errors.go provides the shared helpers that enforce consistency. Pattern A
handlers return one of the HandleError* values; Pattern B uses WarnError:
// Return through RunE — prints "Error: ..." to stderr, returns *exitError{Code: 1}
func HandleError(format string, args ...interface{}) error
// Like HandleError, but emits a structured JSON error to stdout under --json
func HandleErrorRespectJSON(format string, args ...interface{}) error
// Adds a "Hint: ..." line (the …RespectJSON variant routes JSON to stdout)
func HandleErrorWithHint(message, hint string) error
func HandleErrorWithHintRespectJSON(message, hint string) error
// Exit 1 with no message, when the error was already reported
func SilentExit() error
// Pattern B — prints "Warning: ..." to stderr and returns nothing
func WarnError(format string, args ...interface{})
Related Issues
- bd-9lwr - Document inconsistent error handling strategy across codebase (this document)
- bd-bwk2 - Centralize error handling patterns in storage layer
- Future work: Audit all error handling to ensure pattern consistency
References
cmd/bd/errors.go- TheHandleError*/WarnError/SilentExithelpers and theexitErrorsentinel thatmain()maps to an exit codecmd/bd/defer.go- Clean example of Pattern A:return HandleError(...)from aRunEwithSilenceUsage/SilenceErrorssetcmd/bd/init.go- Examples of all three patternscmd/bd/sync.go- Examples of Pattern B for metadata operations and Pattern C for cleanup operations