# Handle errors gracefully

> Improve app robustness by handling errors. Learn about exceptions, errors, `try/catch`, `throw`, and `rethrow`.



In this chapter, make your application more robust
by handling errors gracefully.
Explore exceptions, `try/catch` blocks, and how to
create custom exceptions to manage errors in a structured way.

<SummaryCard>
title: What you'll accomplish
items:
  - title: Distinguish errors and exceptions
    icon: error
  - title: Use try/catch to handle failures
    icon: shield
  - title: Create and throw custom exceptions
    icon: deployed_code_alert
</SummaryCard>

## Prerequisites

Before you begin this chapter, ensure you:

- Have completed Chapter 6 and have a
  working Dart development environment with the `dartpedia` project.
- Understand basic programming concepts like functions and classes.

## Errors versus exceptions

Dart distinguishes between two main types of failures:
**errors** and **exceptions**.

| Concept | `Exception` | `Error` |
| :--- | :--- | :--- |
| **What it indicates** | An expected runtime failure that code can recover from. | A programming bug or flaw in the code. |
| **Common examples** | `FormatException`, `HttpException`, `SocketException`. | `RangeError`, `TypeError`, `StateError`. |
| **Typical causes** | Invalid user input, network failure, missing file. | Off-by-one index, calling a method on `null`. |
| **How to handle** | Catch and handle gracefully (for example, with `try/catch`). | Do not catch; fix the bug in your code. |

### Exceptions

Exceptions represent conditions that you can anticipate and recover from.
For example, when a user enters an unrecognized command-line argument,
your application shouldn't crash with a raw stack trace.
Instead, your code catches the exception,
displays a friendly error message, and
prompts the user with proper usage instructions.

In Dart, custom exceptions typically implement the `Exception` class or
extend an existing exception type like `FormatException`.

### Errors

Errors represent bugs in your logic that
should be fixed during development rather than handled at runtime.
For example, accessing an element beyond the bounds of a list throws a
`RangeError`.
Attempting to catch and suppress a `RangeError` hides the bug and
can leave your application in an unpredictable state.
Instead, let errors propagate so you can inspect the stack trace and
fix the underlying mistake.

In Dart, classes that represent bugs extend or implement `Error`.

## Tasks

The following tasks apply these principles to the `command_runner` package.
You define a custom exception class for invalid user arguments,
use `try/catch` blocks to intercept failures, and
configure `CommandRunner` to handle exceptions gracefully
while letting unexpected errors propagate.

### Task 1: Create a custom ArgumentException

First, define a custom exception class called `ArgumentException` to
represent errors related to command-line arguments.

1.  Create the file `command_runner/lib/src/exceptions.dart`.
    This file contains the definition for your `ArgumentException` class.

1.  Define a class called `ArgumentException` that `extends` `FormatException`.

    ```dart title="command_runner/lib/src/exceptions.dart"
    class ArgumentException extends FormatException {
      /// The command that was parsed before discovering the error.
      ///
      /// This will be empty if the error was on the root parser.
      final String? command;

      /// The name of the argument that was being parsed when the error was
      /// discovered.
      final String? argumentName;

      ArgumentException(
        super.message, [
        this.command,
        this.argumentName,
        super.source,
        super.offset,
      ]);

      @override
      String toString() {
        return 'ArgumentException: $message';
      }
    }
    ```

    This class extends `FormatException`, which
    is a built-in Dart class that implements `Exception`.
    Invalid command-line arguments are an expected condition
    that callers can anticipate and handle gracefully, so
    `ArgumentException` is designed as an exception rather than an `Error`.
    It includes additional properties to store the
    command and argument name associated with the error.
    This provides more context when handling the exception.

    - `command`:
      The command that was being processed when the exception occurred.
    - `argumentName`:
      The name of the argument that caused the exception.


### Task 2: Implement error handling in CommandRunner

Next, update the `CommandRunner` class to
handle potential errors gracefully.
This involves adding an error-handling callback,
using `try/catch` to manage exceptions, and
throwing your new `ArgumentException` when the user provides bad input.

1.  Add the necessary imports.

    In `command_runner/lib/src/command_runner_base.dart`,
    add imports for `dart:async` (to use `FutureOr`) and
    your new `exceptions.dart` file.

    ```dart title="command_runner/lib/src/command_runner_base.dart"
    import 'dart:async'; // Add this line
    import 'dart:collection';
    import 'dart:io';

    import 'arguments.dart';
    import 'exceptions.dart'; // Add this line
    ```

1.  Add an `onError` callback to the `CommandRunner`.

    Modify the CommandRunner to
    accept an optional `onError` function in its constructor.
    This allows users of your package to
    define their own error-handling logic.

    ```dart title="command_runner/lib/src/command_runner_base.dart"
    class CommandRunner {
      // Add a constructor that accepts the optional callback.
      CommandRunner({this.onError});

      final Map<String, Command> _commands = <String, Command>{};

      UnmodifiableSetView<Command> get commands =>
          UnmodifiableSetView<Command>(<Command>{..._commands.values});

      // Define the onError property.
      FutureOr<void> Function(Object)? onError;

      // The rest of the class implementation...
    }
    ```

    This change introduces a nullable `onError` property.
    The `FutureOr<void> Function(Object)?` type means it's a function that
    takes an `Object` and returns a `Future` or nothing, and it might be null.

1.  Update the run method to use `try`/`catch`.

    Wrap the logic inside the run method in a `try`/`catch` block.
    If an exception occurs, this block catches it and either
    passes it to the `onError` callback or rethrows it if no callback is provided.
    `rethrow` preserves the original error and stack trace.

    ```dart title="command_runner/lib/src/command_runner_base.dart"
    Future<void> run(List<String> input) async {
      // [Step 6 update] try/catch added
      try {
        final ArgResults results = parse(input);
        if (results.command != null) {
          Object? output = await results.command!.run(results);
          print(output.toString());
        }
      } on Exception catch (exception) {
        if (onError != null) {
          onError!(exception);
        } else {
          rethrow;
        }
      }
    }
    ```

    Notice the use of `on Exception catch (exception)`.
    In Dart, a bare `catch (e)` intercepts all thrown objects,
    including `Error` instances.
    Specifying `on Exception` ensures that your code catches only
    recoverable exceptions,
    allowing bugs to propagate uncaught so you can fix them.

1.  Add validation to the `parse` method.

    Finally, replace the existing `parse` method in `command_runner_base.dart`
    with the following updated version.
    It includes checks that throw your custom `ArgumentException`
    whenever it detects invalid user input.

    ```dart title="command_runner/lib/src/command_runner_base.dart"
    // [Step 6 update] This method is replaced entirely.
    ArgResults parse(List<String> input) {
      ArgResults results = ArgResults();
      if (input.isEmpty) return results;

      // Throw an exception if the command is not recognized.
      if (_commands.containsKey(input.first)) {
        results.command = _commands[input.first];
        input = input.sublist(1);
      } else {
        throw ArgumentException(
          'The first word of input must be a command.',
          null,
          input.first,
        );
      }

      // Throw an exception if multiple commands are provided.
      if (results.command != null &&
          input.isNotEmpty &&
          _commands.containsKey(input.first)) {
        throw ArgumentException(
          'Input can only contain one command. Got ${input.first} and ${results.command!.name}',
          null,
          input.first,
        );
      }

      // Section: Handle options, including flags.
      Map<Option, Object?> inputOptions = {};
      int i = 0;
      while (i < input.length) {
        if (input[i].startsWith('-')) {
          var base = _removeDash(input[i]);
          // Throw an exception if an option is not recognized for the given command.
          var option = results.command!.options.firstWhere(
            (option) => option.name == base || option.abbr == base,
            orElse: () {
              throw ArgumentException(
                'Unknown option ${input[i]}',
                results.command!.name,
                input[i],
              );
            },
          );

          if (option.type == OptionType.flag) {
            inputOptions[option] = true;
            i++;
            continue;
          }

          if (option.type == OptionType.option) {
            // Throw an exception if an option requires an argument but none is given.
            if (i + 1 >= input.length) {
              throw ArgumentException(
                'Option ${option.name} requires an argument',
                results.command!.name,
                option.name,
              );
            }
            if (input[i + 1].startsWith('-')) {
              throw ArgumentException(
                'Option ${option.name} requires an argument, but got another option ${input[i + 1]}',
                results.command!.name,
                option.name,
              );
            }
            var arg = input[i + 1];
            inputOptions[option] = arg;
            i++;
          }
        } else {
          // Throw an exception if more than one positional argument is provided.
          if (results.commandArg != null && results.commandArg!.isNotEmpty) {
            throw ArgumentException(
              'Commands can only have up to one argument.',
              results.command!.name,
              input[i],
            );
          }
          results.commandArg = input[i];
        }
        i++;
      }
      results.options = inputOptions;

      return results;
    }

    String _removeDash(String input) {
      if (input.startsWith('--')) {
        return input.substring(2);
      }
      if (input.startsWith('-')) {
        return input.substring(1);
      }
      return input;
    }
    ```

    This updated parse method now actively defends against bad input.
    Specifically, the new throw statements handle several common error cases:

    -   **Unknown commands:**
        The first `if`/`else` block ensures the
        first argument is a valid command.
    -   **Multiple commands:**
        It checks that the user hasn't tried to
        run more than one command at a time.
    -   **Unknown options:**
        The `orElse` parameter within `firstWhere` now throws an
        exception if a user provides a flag or option (like `--foo`) that
        hasn't been defined for that command.
    -   **Missing option values:**
        It ensures that an option (like `--output`) is followed by a value and
        not another option or the end of the input.
    -   **Too many arguments:**
        It enforces a rule that commands can
        only have one positional argument.

### Task 3: Update cli.dart to use the new error handling

Modify `cli/bin/cli.dart` to use the new error handling in `CommandRunner`.

1.  Open the `cli/bin/cli.dart` file.

1.  Update the `main` function to pass in
    an `onError` function to the `CommandRunner`:

    ```dart title="cli/bin/cli.dart"
    import 'package:command_runner/command_runner.dart';

    const version = '0.0.1';

    void main(List<String> arguments) {
      // [Step 6 update] Add onError method
      var commandRunner = CommandRunner(
        onError: (Object error) {
          if (error is Error) {
            throw error;
          }
          if (error is Exception) {
            print(error);
          }
        },
      )..addCommand(HelpCommand());
      commandRunner.run(arguments);
    }
    ```

    This code passes an `onError` callback to `CommandRunner`.
    The callback rethrows any `Error` so the application crashes,
    while printing any `Exception` to the console so the user sees
    the error message.

### Task 4: Update command_runner library exports

Make `ArgumentException` available to the `command_runner` library.

1.  Open `command_runner/lib/command_runner.dart`, and
    add the following exports:

    ```dart title="command_runner/lib/command_runner.dart"
    /// Support for doing something awesome.
    ///
    /// More dartdocs go here.
    library;

    export 'src/arguments.dart';
    export 'src/command_runner_base.dart';
    export 'src/help_command.dart';
    export 'src/exceptions.dart'; // Add this line

    // TODO: Export any libraries intended for clients of this package.
    ```

    In Dart packages, files inside `lib/src/` are private implementation details.
    Exporting `src/exceptions.dart` from `lib/command_runner.dart` exposes
    `ArgumentException` as part of the package's public API so callers
    (like `cli.dart`) can import and use it.

### Task 5: Test the new error handling

Test the new error handling by running the application with invalid arguments.

1.  Open your terminal and navigate to the `cli` directory.

1.  Run the command `dart run bin/cli.dart invalid_command`.

    You should see the following output:

    ```bash
    ArgumentException: The first word of input must be a command.
    ```

    This confirms that the `ArgumentException` is
    being thrown and caught correctly.

## Review

<SummaryCard>
title: What you accomplished
subtitle: Here's a summary of what you built and learned in this lesson.
completed: true
items:
  - title: Distinguished errors from exceptions
    icon: error
    details: >-
      You learned that subtypes of `Error` indicate
      programming bugs and aren't intended to be caught,
      while subtypes of `Exception` represent
      recoverable failures that your code can handle gracefully.
  - title: Used try-catch blocks to handle failures
    icon: shield
    details: >-
      You wrapped risky code in `try`-`catch` blocks to intercept exceptions.
      You used `on ExceptionType catch (e)` to handle specific types and
      `rethrow` to repropagate exceptions while preserving the stack trace.
  - title: Created and threw custom exceptions
    icon: deployed_code_alert
    details: >-
      You built a `ArgumentException` class that extends `FormatException` to
      provide context-rich error information.
      Then you used `throw` to signal validation failures with
      meaningful messages for better debugging and user feedback.
</SummaryCard>

## Quiz

<Quiz title="Check your understanding" id="error-handling" />

## Next lesson

In the next lesson, learn about
advanced object-oriented features in Dart,
including enhanced enums and extensions.
Improve the output formatting and add color to your CLI application.

