Errors and exit codes
CONGA classifies every failure it detects into exactly one of five base categories. An error returned by a command’s own Run or lifecycle hook comes back unchanged. Match the category, and read the specifics from the message (field, token, command path, suggestions).
Exit codes
Section titled “Exit codes”app.Exit(err) terminates with one of three codes:
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Command runtime failure (Runner.Run or lifecycle hooks), schema-build failure (ErrSchema), or configuration failure (ErrConfig, including environment-, configuration-, and default-sourced value failures) |
| 2 | Usage error: invalid command-line input — unknown flags, parse failures, coercion failures, constraint violations, missing required input — and internal completion failures with a diagnostic on stderr |
Built-in requests (--help, help, --version, version, and opt-in --why and --completion <shell>) write to stdout during app.Run() and return nil on clean completion.
Base categories
Section titled “Base categories”| Sentinel | Stage |
|---|---|
conga.ErrSchema |
Schema building: tag linting, duplicates, invalid order (programmer errors at startup) |
conga.ErrParse |
Command-line tokenization and parsing |
conga.ErrCoerce |
Command-line string → typed value conversion |
conga.ErrValidation |
Command-line constraints and semantic checks |
conga.ErrConfig |
Config file and .env reading, parsing, and key resolution, plus conversion and constraint failures for environment-, configuration-, and default-sourced values |
Which category a value failure gets
Section titled “Which category a value failure gets”Two rules decide the category of a value failure.
The source decides the exit path. A command-line token is a usage error: ErrCoerce when conversion fails, ErrValidation when a constraint fails, exit 2. A value from an environment variable, a configuration file, or a default tag classifies under ErrConfig only: exit 1, no usage block, and errors.Is(err, conga.ErrCoerce) and errors.Is(err, conga.ErrValidation) both report false. The message keeps its origin:
app: error: invalid integer value "abc" for flag --portapp: error: invalid integer value "abc" for flag --port (from environment variable APP_PORT)app: error: invalid integer value "abc" for flag --port (from config key "port")app: error: invalid integer value "abc" for flag --port (from default value)The first is a usage error with exit 2. The other three are ErrConfig with exit 1. errors.As and errors.Is still reach the original cause, so an application TextUnmarshaler error, a stdlib *fs.PathError, and a sentinel such as fs.ErrNotExist remain inspectable. Only the category sentinels stop at ErrConfig: errors.Is reports false for ErrCoerce, ErrValidation, ErrParse, and ErrSchema even when the cause wraps one.
The stage decides ErrCoerce versus ErrValidation. A failure while converting the text is ErrCoerce; a check on the converted value is ErrValidation. For example, a File field with executable:"true":
$ app --exe nosuchtoolError:app: error: exec: "nosuchtool": executable file not found in $PATH for flag --exeError$ app --exe /usr/local/bin/nosuchtoolError:app: error: stat /usr/local/bin/nosuchtool: no such file or directory for flag --exeErrorThe bare name is resolved on $PATH during conversion, so the failure is ErrCoerce. The absolute path converts cleanly and fails File.Validate, so it is ErrValidation. Both exit 2 because the value came from the command line. A wrong path kind on a converted value — a directory where a file was expected — is ErrValidation. The same check inside FileContent runs while converting its text, so for a command-line value it stays ErrCoerce.
For a command-line value, conversion-time failures stay under ErrCoerce even when they mean “not found”. --why makes the difference visible: a conversion-time $PATH miss aborts before the report renders, while the post-coercion File.Validate error is skipped when --why renders the report.
Usage and completion classification
Section titled “Usage and completion classification”Use conga.IsUsageError(err) to decide whether an error is input-related (exit 2) versus a runtime failure (exit 1). Errors caused by invalid command-line input satisfy the conga.UsageError interface:
type UsageError interface { error IsUsageError() bool CommandPath() string Usage() string}CommandPath()returns the invocation path of the command where the failure occurred (for example,"cloudctl deploy").Usage()returns the syntax usage summary string for that command.
Internal completion failures satisfy the conga.CompletionError interface and are detected with conga.IsCompletionError(err):
type CompletionError interface { error IsCompletionError() bool}The concrete error implementations (parse, coercion, validation, config) are unexported. IsUsageError, IsCompletionError, UsageError, CompletionError, and the base category sentinels form the public classification API.
Feature-gating and map-folding failures
Section titled “Feature-gating and map-folding failures”Feature gating and map folding classify errors by the input source that introduced the invalid data:
| Failure | Category | Exit |
|---|---|---|
| Inactive gated flag or subcommand supplied on the command line, unknown feature key, or invalid feature value | ErrParse / ErrValidation (usage error) |
2 |
| Unknown feature key in a config file | ErrConfig |
1 |
| Invalid feature value in a config file | ErrConfig |
1 |
| Config key naming a flag whose gating feature is inactive | ErrConfig |
1 |
| Config key naming a flag whose gating feature the command line or environment turned off | Ignored | – |
| Environment variable naming an inactive gated flag | Ignored (the inactive flag never reaches environment binding) | – |
| Unknown feature key in the feature map environment variable | ErrConfig |
1 |
| Invalid feature value in the feature map environment variable | ErrConfig |
1 |
| Malformed map flag entry in a config file (even when overridden by CLI) | ErrConfig |
1 |
| Malformed map flag syntax in an environment variable | ErrConfig |
1 |
Invalid format passed to --why or --why=json requested without conga.WhyOptionJSON() |
ErrValidation (usage error) |
2 |
Runtime error returned from Bootstrapper.Bootstrap |
ErrConfig |
1 |
Schema errors (ErrSchema)
Section titled “Schema errors (ErrSchema)”Programmer errors during schema construction abort at startup before execution begins (exit code 1):
- Declaring
conga.Features[T]orfeature:"..."tags without callingapp.EnableFeatures(). - Declaring both
envandenvprefixon aconga.Featurescontainer, or a feature-fieldenvtag under a combined-map container. - Binding one environment variable through two feature fields (explicitly or through prefix derivation), or through a feature and a flag.
- Binding a flag or feature to the environment variable the app reads a config file path from (
<PREFIX>_CONFIG, or theConfigFilefield’senvtag):struct CLI field Config: schema error: environment variable "PC_CONFIG" is bound by both the config file variable and flag --config; give the flag another env tag or exclude it with env:"-". - Combining
conga.ConfigExplicit(...)withconga.ConfigPaths(...)orconga.ConfigCascading(). - Declaring the
bootstraptag when neither the declaring command nor an ancestor implementsconga.Bootstrapper. - Combining the
bootstrapandfeaturetags on the same field. - Declaring the
bootstraptag on unsupported field types (structs, pointers, interfaces). - Inconsistent
stagetags violating the all-or-nothing requirement on feature structs. - Declaring
enumon a path field (conga.File,conga.Dir,conga.FileContent, a filterable type, or afile,dir,exec, orsymlinkpredictor tag):struct Deploy field Manifest: schema error: invalid struct tag: tag "enum" is not supported on conga.File; use tag "glob" to filter completion candidates, or a string field with tag "enum" to accept a fixed set of names. - Setting
enumhint:"-"on a field without declared enums, or where thehelptag already references{{enum}}. - Ancestor flag shadowing across command-subcommand hierarchies (
ErrDuplicateFlag), including the built-in version command’s--jsonand a CLI-exposedFeatures[T]flag. - Built-in short flag collisions: assigning a short rune via
app.HelpShortFlagorapp.VersionShortFlagthat collides with an application flag, or assigning the same rune to both built-in flags (ErrDuplicateFlag). - Declaring
default,xor, oroneofon aRequiredFlag[T]. - Invalid group definitions: declaring
defaulton aoneofmember, two members of the sameoneoforxorgroup sharing anandgroup, axororandgroup with fewer than two members, aoneofgroup with fewer than two members unless its sole member is aCounter, or an empty or whitespace group name. - Invalid section definitions: declaring a
sectionvalue with leading or trailing whitespace. - CONGA tags on plain non-container fields, such as
nameorhelpon a plain struct field, instead of silently ignoring them. - Unrecognized struct tags without calling
app.AllowTags(...)(includingconga:"..."directives). - A boolean tag (
hidden,negatable,bootstrap,implicit,safe,multi, or a domain type’s boolean tag such asexisting) with a value other than empty,true, orfalse:struct CLI field Debug: schema error: invalid struct tag: tag "hidden" expects "true" or "false", got "yes". - Declaring
ConfigFileorFeatureson any command struct other than the root. - A flag or positional argument whose type, slice element type, or map key or value type has no parser:
struct CLI field Zone: schema error: unsupported type *time.Location; register a parser with app.Use(timezone.RegisterLocation). The hint namesapp.RegisterType, or the domain-package binding for*time.Location,*user.User,*user.Group, and*net.Interface. - A leaf command that does not implement
conga.Runner:struct LeafCmd: schema error: runner not implemented: implement conga.Runner: Run(context.Context, *conga.Session) error.
Panics
Section titled “Panics”Developer misuse of the API panics with a fixed message instead of returning an error. Schema errors are not panics, and Run returns them as ErrSchema.
| Misuse | Panic message |
|---|---|
conga.New given more than one root |
conga: New accepts at most one root instance |
conga.New given a nil root |
conga: New requires a non-nil root instance |
app.Predictor with an empty name |
conga: predictor name cannot be empty |
app.Predictor with a built-in predictor’s name |
conga: cannot register predictor "<name>": reserved built-in predictor name |
app.Predictor with a name already registered |
conga: predictor "<name>" is already registered |
RegisterType with a nil parser, or on a nil app |
conga: RegisterType requires a non-nil parser, conga: RegisterType requires a non-nil app |
RegisterType for a map or slice type |
conga: RegisterType does not accept map type <M>; maps bind entry by entry, so register the key or value type instead, conga: RegisterType does not accept slice type <S>; slices bind element by element, so register the element type instead |
RegisterType for a slice or map type that implements encoding.TextUnmarshaler |
conga: RegisterType does not accept <T>; it implements encoding.TextUnmarshaler, so it binds as one value without registration |
conga.ConfigPaths() with no paths, or an empty path |
conga: app.ConfigOptions(conga.ConfigPaths(...)): at least one path is required, …: path entries must be non-empty |
conga.ConfigExplicit("") |
conga: app.ConfigOptions(conga.ConfigExplicit(...)): the explicit path cannot be empty |
A nil context.Context passed to RunContext, or to Run on HelpCommand, VersionCommand, or CompletionCommand |
conga: nil Context |
A second Run or RunContext on the same App |
conga: App already executed |
session.Root[T]() with a T other than the root command type |
conga: Session.Root[<T>] called, but root command type is <root> |
A method called on a nil *ConfigDocument |
conga: nil ConfigDocument; use the zero value (var document conga.ConfigDocument) |
A panic whose message starts with conga: invariant violation: is a bug in CONGA, not misuse, and is worth reporting.
Custom error handling
Section titled “Custom error handling”Custom error handling inspects the error returned by app.Run() or app.RunContext(ctx) directly instead of delegating to app.Exit(err). The returned error carries the classification. conga.IsUsageError(err) distinguishes command-line input errors, errors.AsType[conga.UsageError](err) yields the UsageError for CommandPath() and Usage(), conga.IsCompletionError(err) identifies internal completion failures, and errors.Is matches the base category sentinels.
An environment-, configuration-, or default-sourced coercion or constraint failure still implements conga.UsageError, but its IsUsageError() reports false and it classifies under ErrConfig. Test the classification through conga.IsUsageError(err), not through the type assertion alone:
if err := app.RunContext(ctx); err != nil { if conga.IsUsageError(err) { usageErr, _ := errors.AsType[conga.UsageError](err) fmt.Fprintf(os.Stderr, "usage error in %s: %v\n", usageErr.CommandPath(), err) fmt.Fprintf(os.Stderr, "%s\n", usageErr.Usage())
os.Exit(2) }
if errors.Is(err, conga.ErrConfig) { fmt.Fprintf(os.Stderr, "configuration failure: %v\n", err)
os.Exit(78) }
if conga.IsCompletionError(err) { fmt.Fprintf(os.Stderr, "completion failure: %v\n", err)
os.Exit(70) }
fmt.Fprintf(os.Stderr, "Error: %v\n", err) os.Exit(1)}About error reporting covers the separation of error values from process termination.
Usage rendering on errors
Section titled “Usage rendering on errors”UsageOnError(mode) controls what Exit prints below a usage error:
| Mode | Output |
|---|---|
conga.UsageSummary (default) |
Clean error, 1–2 line syntax, --help hint |
conga.UsageFull |
Clean error plus the complete help screen |
conga.UsageHint |
Clean error plus a single Run '<cmd> --help' hint |
conga.UsageSilence |
Only the clean error message |
Self-describing command-line value errors render only the error line regardless of the configured mode. Environment-, configuration-, and default-sourced value failures are not usage errors, so they always render as a single app: error: ... line with exit 1. Self-describing command-line value errors are those whose message already names the flag or argument and the offending value, such as coercion failures (unknown byte size unit "XB" in "5XB" (accepted: B, kB, MB, GB, TB, PB, EB, KiB, MiB, GiB, TiB, PiB, EiB) for flag --max-memory, ambiguous byte size unit "KB" in "5KB": use kB (1000) or KiB (1024) for flag --max-memory) and value-constraint violations ("/etc/passwd" is a file, but a directory was expected for flag --dir, score 150 must be between 0 and 100 for flag --score). Errors that benefit from usage context — unknown commands and flags, missing required flags/arguments, mutually exclusive or grouped flags — keep the mode’s rendering. A group failure whose members all came from the environment or a config file classifies under ErrConfig instead and renders as the single error line with exit 1.