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

  1. Add a sentinel for a duplicate title and a status for it. Which layer detects the duplicate, and where is the sentinel defined?
  2. Make Wrap return the error unchanged for ErrEmptyTitle and run the empty-title case. Which message changes, and is that better?
  3. 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.

  1. What is a sentinel error?

    Answer

    A package-level value compared with errors.Is

    It exists to be tested.

  2. Where does ErrEmptyTitle live?

    Answer

    With the model that produces it

    The producer owns the error.

  3. What does %w do in fmt.Errorf?

    Answer

    Keeps the cause for errors.Is and errors.As

    It is the wrapping verb.

  4. Which status is a missing task?

    Answer

    3

    ExitCode maps ErrNotFound to 3.

  5. Which status is a bad argument?

    Answer

    2

    main rejects it before the store.

  6. What is the status of a generic error?

    Answer

    1

    It is the catch-all.

  7. 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.

  8. What does Wrap do with a nil error?

    Answer

    Returns nil

    A caller can wrap without checking.

  9. Why distinguish statuses at all?

    Answer

    A script branches on the number instead of parsing text

    The status is the machine contract.

  10. 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