Error Catalogue¶

This document catalogues the sentinel errors defined in GTB's own pkg/ packages: the ones a tool built on GTB is most likely to check for with errors.Is. GTB uses gitlab.com/phpboyscout/go/errors for wrapping and stack traces (a stdlib-only package with the same symbols as cockroachdb/errors, which GTB no longer depends on). Every extracted module GTB consumes has its own sentinels, documented on its own microsite; see Module error catalogues below for the links.

Use errors.Is(err, target) to check for sentinel errors, this traverses wrapped error chains correctly.

import "gitlab.com/phpboyscout/go/errors"

if errors.Is(err, root.ErrNoConfigFile) {
    // prompt user to run init
}

pkg/cmd/root¶

pkg/props¶

Raised by the feature registry while a tool's feature set is being assembled at init() time. Every one is a programming error in the tool or a plugin it imports, not a runtime condition, they surface as a panic through RegisterFeature rather than something a command can recover from.

gitlab.com/phpboyscout/go/controls¶

ErrShutdown (returned by Wait() in some shutdown paths, generally expected: log at debug and exit cleanly) is the sentinel a GTB command may see. Full catalogue on the module's reference.

gitlab.com/phpboyscout/go/errorhandling¶

ErrNotImplemented (constructed via NewErrNotImplemented(issueURL string) error for a command stubbed with a tracking issue) and ErrRunSubCommand (a parent command invoked without a subcommand) are the two sentinels a GTB command commonly returns. Full catalogue on the module's error reference.

pkg/logger¶

pkg/cmd/root¶

pkg/setup¶

ErrSignatureInvalid, ErrSignatureMissing, ErrWeakKey and the other key-resolution sentinels live in gitlab.com/phpboyscout/go/signing/verify; SelfUpdater re-surfaces them during Update(). Full list on the module's reference.

Module error catalogues¶

Every other extracted module GTB consumes defines its own sentinels, documented on its own microsite rather than duplicated here:

go/controls and go/errorhandling each surface one sentinel a GTB command commonly checks for; see the sections above.

Notes¶

Internal package errors¶

The internal/ packages define additional sentinel errors for generator and code-generation use. These are not part of the public API and may change without notice:

Adding new errors¶

When adding a sentinel error to a pkg/ package:

1. Define it as a package-level var using NewSentinel(kind, msg), not New: at package scope New captures its stack at initialisation, which points at runtime.doInit rather than anywhere the error was returned. Kinds are namespaced gtb.<package>.<name>:

   var ErrMyCondition = errors.NewSentinel("gtb.mypackage.my_condition", "description of the condition")
   

2. Add an entry to this catalogue with a description and handling guidance.
3. Use errors.Wrap(err, "context") to add call-site context when returning the error through multiple layers.