Error handling design and input validation

A signup form can fail in many ways: a username of one letter, a name of 1 MB pasted by a script, a disk that is full, a bug in the code that saves the account. Error handling design is the set of decisions about each one: does the code throw it or return it, what does the person at the keyboard read, and what does the log keep?

This lesson makes those decisions for a small Dart signup. Every program in it ran on Dart 3.13.5, and the first decision is the one every check faces: how to report that it failed.

One rule, three ways to report that it failed

A username must be 3 to 20 characters from a-z, 0-9 and the underscore. This program reports a broken rule in each of the three ways Dart offers, and calls each one on the same three inputs:

// One username rule, reported three ways: an exception, a nullable return and a sealed result type.
final _shape = RegExp(r'^[a-z0-9_]+$');

String? _problem(String s) {
  if (s.length < 3 || s.length > 20) return 'must be 3 to 20 characters, not ${s.length}';
  if (!_shape.hasMatch(s)) return 'may hold only a-z, 0-9 and _';
  return null;
}

// 1. An exception: the caller must remember to catch it.
class UsernameException implements Exception {
  UsernameException(this.reason);
  final String reason;
}

String checkUsername(String s) {
  final problem = _problem(s);
  if (problem != null) throw UsernameException(problem);
  return s;
}

// 2. A nullable return: the type forces a null check, but null says nothing about why.
String? usernameOrNull(String s) => _problem(s) == null ? s : null;

// 3. A sealed result: the type forces a switch, and the refusal carries its reason.
sealed class UsernameCheck {}

class Accepted extends UsernameCheck {
  Accepted(this.name);
  final String name;
}

class Refused extends UsernameCheck {
  Refused(this.reason);
  final String reason;
}

UsernameCheck usernameCheck(String s) {
  final problem = _problem(s);
  return problem == null ? Accepted(s) : Refused(problem);
}

void main() {
  for (final input in ['asha_k', 'A', 'ravi.kumar']) {
    print('"$input"');
    try {
      print('  exception: accepted ${checkUsername(input)}');
    } on UsernameException catch (e) {
      print('  exception: refused, ${e.reason}');
    }
    print('  nullable:  ${usernameOrNull(input) ?? 'null, with no reason'}');
    final shown = switch (usernameCheck(input)) {
      Accepted(:final name) => 'accepted $name',
      Refused(:final reason) => 'refused, $reason',
    };
    print('  result:    $shown');
  }
}

"asha_k"
  exception: accepted asha_k
  nullable:  asha_k
  result:    accepted asha_k
"A"
  exception: refused, must be 3 to 20 characters, not 1
  nullable:  null, with no reason
  result:    refused, must be 3 to 20 characters, not 1
"ravi.kumar"
  exception: refused, may hold only a-z, 0-9 and _
  nullable:  null, with no reason
  result:    refused, may hold only a-z, 0-9 and _

All three accepted asha_k and refused the other two. The exception carried the reason, but nothing in checkUsername’s type told its caller to catch it. The nullable return forced a null check through its type String?, yet A and ravi.kumar both came back as a bare null: the reason was lost. The sealedsealed class: A class marked sealed: it cannot be extended or implemented outside its own library, so the compiler knows all its direct subtypes and can check that a switch over them is exhaustive. More in “Validating JSON in Dart with patterns” UsernameCheck did both. Its switch has to name Accepted and Refused before it compiles, and Refused holds the reason, the pattern that validating JSON with patterns used for request bodies.

Choose by what the failure means to its caller

None of the three is always right. The choice follows from what the failure means: is it part of normal use, does the caller need the reason, and how far away is the code that can act on it? Answer those questions in the table:

The short version: throw an exceptionexception: An object a Dart program throws to report a failure it is expected to handle, such as text that does not parse or a file that is missing. Classes that implement Exception can be caught by type with an on clause. More in “Dart exceptions and errors: try, catch, finally” for a failure outside normal use, such as a full disk or a lost connection, and let a caller several layers up catch it. Return null when absence is the only outcome and needs no reason, such as a lookup that finds no user. Return a result typeresult type: A type whose values are either a success holding a value or a failure holding a reason, such as Ok and Bad, so that expected failures are returned instead of thrown. More in “Validating JSON in Dart with patterns” when the failure is an everyday outcome whose reason the caller must show, such as a refused form field. A bug is none of these: it stays an Error that reaches the top.

Good error handling design also decides what happens around those calls. Input validation decides the order of the checks on untrusted inputuntrusted input: Data that comes from outside the program, such as a request body, a file or a message, and may have any shape or content until the program has checked it. More in “Validating JSON in Dart with patterns”: its size first, then its type, then an allowlistallowlist: A list of what is accepted, such as the field names an endpoint takes. Anything not on it is refused, instead of trying to list everything that should be blocked. More in “Validating JSON in Dart with patterns” of the characters it may hold. An assert cannot do input validation, because dart run ignores assertionsassertion: A check written as assert(condition, message) that throws an AssertionError when the condition is false, but only while assertions are enabled, as with --enable-asserts or in Flutter debug mode.. A boundary at the edge of the program turns each failure into a message, a log line and an exit code.

Validating untrusted input in a safe order, with measured runs Pro: opens with a Pro, Premium or Ultimate pass

Messages, logs and one boundary that sets the exit code Pro: opens with a Pro, Premium or Ultimate pass

Practise

The self-check on reporting a failure and choosing how starts with whichever of the two ideas you know less well, and a question you miss returns once before the session ends:

Interview questions

Warm-up (2-5 years): When should a Dart function return null instead of throwing?

Return null when “nothing there” is a normal answer and the caller needs no reason: a lookup by id that finds no user, a cache miss, an optional setting that is not set. The nullable return type then makes every caller handle the absent case before using the value, which an exception does not. Throw instead when the failure is outside normal use, such as a lost connection or a corrupt file, or when the caller must know why it failed: a bare null cannot tell one cause from another, which is when a sealed result type with a reason fits better.

Three longer questions put these choices to work on real designs:

Key takeaways

• One failed check can be reported as an exception, a nullable return or a sealed result, and only the sealed result both forces the caller to handle it and carries the reason.
• Throw for failures outside normal use, return null when absence needs no reason, and return a sealed result for everyday outcomes the caller must explain.
• Errors that report bugs are never returned as results: they reach the top, where the code gets fixed.