errorhandling¶

Turn an error into something a user can act on. Attach a hint that says what to do; attach the exit code to the error itself; report it once, at the top; and keep stack traces for when someone asks for them.

go get gitlab.com/phpboyscout/go/errorhandling

gitlab.com/phpboyscout/go/errorhandling is the error-reporting layer extracted from go-tool-base. It adds a small reporting pipeline over go/errors: levels, outcomes, exit codes, debug-gated stacks, and an optional support-channel message.

Why¶

• Two jobs, kept separate. Creating an error (with context, hints, and a stack) is go/errors' job. Reporting one — deciding the level, the exit code, and what the user sees — is this package's. See the reporting model.
• The error carries its exit code. WithExitCode(err, 3) travels with the error through every wrap, so the code that knows why something failed decides how the process exits — and every exit stays on one path instead of os.Exit calls scattered through the tree.
• Hints, not walls of text. The message says what broke; the hint says what to do about it. Hints are surfaced as their own field, so the message stays short and the advice stays visible.
• The error carries how the program should end. An Outcome states the exit code, the level, and whether to print usage — so an error can be terminal and successful, which a closed switch over sentinels could never express.
• Quiet when it should be. Stack traces appear only when debug logging is on. A user pressing Ctrl+C is not a failure, so Quietly() reports at the right code without shouting at them.
• Framework-free, and dependency-free. go/errors is stdlib-only, so adding this module adds this module. No CLI framework, no config system — a depfootprint_test.go guard keeps it that way, and printing usage goes through a caller-supplied seam.

Where next¶

What this package does not do¶

It reports errors. It does not exit, catch signals, recover panics, redact secrets, retry anything, or send a crash report — Fatal returns the code it thinks the process should use and leaves acting on it to main. Reports go to the *slog.Logger you supply and nowhere else — there is no writer, no colour control and no format control of its own.

Within reporting, the sharp edges worth knowing before you commit: an error carrying an outcome overrides the level and code you asked for, Quietly is ignored by Error and Warn, and details are not debug-gated. The full list is on the limitations page.

Reference¶

The reference section covers every exported symbol, the exact behaviour of each level, how the exit code is resolved, and the fields a report emits.

Signatures and doc comments are also published on pkg.go.dev.

Further reading¶

The blog carries a curated route through this subject: Building a command-line tool in Go collects everything written about it, ordered so you can start at the beginning rather than newest-first.