Capstone 2: errors and exit codes
A command has three kinds of error: a mistake in the words the user typed, a mistake in the input the program can explain, and a bug or a broken environment. Each gets a status so a shell and a script can tell them apart: 2 for the arguments, 3 for a task that does not exist, 4 for a bad title, 1 for anything else. The mapping is one function and a handful of sentinels.
Sentinel errors
A sentinel is a package-level error compared with errors.Is. ErrEmptyTitle lives with the model because New produces it, and ErrNotFound lives with the store because the store produces it. A caller can wrap either one and still compare, which is the rule that makes wrapping worth the extra words.
// ErrEmptyTitle is returned when a task has no title.
var ErrEmptyTitle = errors.New("title is required")
// Task is one item of the list.
type Task struct {
package tasks
import (
"errors"
"fmt"
)
// ErrNotFound is returned for an id that does not exist.
var ErrNotFound = errors.New("task not found")
// ExitCode maps an error to the status the command exits with.
func ExitCode(err error) int {
switch {
case err == nil:
return 0
case errors.Is(err, ErrNotFound):
return 3
case errors.Is(err, ErrEmptyTitle):
return 4
default:
return 1
}
}
// Wrap adds the operation to an error without losing the cause.
func Wrap(op string, err error) error {
if err == nil {
return nil
}
return fmt.Errorf("%s: %w", op, err)
}
The placeholder error is built with fmt.Errorf and is not a sentinel: no caller needs to act on it differently from any other bad input, and the message is the useful part. A sentinel exists to be tested, not to be numerous.
Wrapping
Wrap adds the operation to the error and keeps the cause with %w. The user reads toggle: task not found and the code still finds ErrNotFound underneath, which is what makes ExitCode work through a stack of calls. A nil error stays nil, so a caller can wrap without checking first.
ExitCode
The function is a switch on errors.Is, and the numbers are the contract with the shell: 3 means the task was not found, 4 means the title was empty. A program that always exits 1 forces a script to parse the message, which is the reason to distinguish the cases at all.
The statuses in a run
The commands below exercise each status against the file from the previous lesson. The output and the status are both real; the echo after each command prints what the shell saw.
TASKS_FILE=/tmp/tasks-demo.json ./bin/tasks done 9 ; echo "exit status: $?"
tasks: toggle: task not found
exit status: 3
TASKS_FILE=/tmp/tasks-demo.json ./bin/tasks add " " ; echo "exit status: $?"
tasks: title is required
exit status: 4
TASKS_FILE=/tmp/tasks-demo.json ./bin/tasks add "TODO" ; echo "exit status: $?"
tasks: title "TODO" is a placeholder, write the real one
exit status: 1
TASKS_FILE=/tmp/tasks-demo.json ./bin/tasks done abc ; echo "exit status: $?"
tasks: id must be a number
exit status: 2
The first message says toggle: and the second does not, because the first error passed through the command layer and the second came straight from New. Both are readable, and the status is the part a script uses. The last one never reached the store: main rejected the id itself.
Errors for users and bugs
A user error is expected, has a useful message and a specific status. A bug is unexpected, has a status of 1 and belongs in a log with more context than a user should see. The two must not share a message format: task not found is for the user, and cannot read /home/x/tasks.json: permission denied is for the user too, but the stack of the programmer is not. The command prints the first on stderr and exits; it does not recover from it.
The next lesson tests all of this with a fake store, so the statuses are checked without a file.
Exercises
- Add a sentinel for a duplicate title and a status for it. Which layer detects the duplicate, and where is the sentinel defined?
- Make Wrap return the error unchanged for ErrEmptyTitle and run the empty-title case. Which message changes, and is that better?
- Write a shell script that runs the command and branches on status 3 and 4. Why is a message parse a worse contract than a status?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What is a sentinel error?
Answer
A package-level value compared with errors.Is
It exists to be tested.
-
Where does ErrEmptyTitle live?
Answer
With the model that produces it
The producer owns the error.
-
What does %w do in fmt.Errorf?
Answer
Keeps the cause for errors.Is and errors.As
It is the wrapping verb.
-
Which status is a missing task?
Answer
3
ExitCode maps ErrNotFound to 3.
-
Which status is a bad argument?
Answer
2
main rejects it before the store.
-
What is the status of a generic error?
Answer
1
It is the catch-all.
-
Why not make every error a sentinel?
Answer
A sentinel exists for callers to test, not to be numerous
The placeholder error is a message.
-
What does Wrap do with a nil error?
Answer
Returns nil
A caller can wrap without checking.
-
Why distinguish statuses at all?
Answer
A script branches on the number instead of parsing text
The status is the machine contract.
-
Where does a bug go?
Answer
Status 1 and a log with context
The user does not need the programmer stack.
The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev