Skip to main content

Error Handling

Control Flow introduced try and catch. This page covers what you can throw, what Stof's own errors look like, and how errors reach your app.

Throw Anything​

throw takes any value. A string is the simplest. An object carries structure, which is useful when the code that catches it needs to decide what to do:

throw-object.stofPlayground ↗
fn charge(amount: float) {
  if (amount > 500) throw(new { code: 402, reason: 'over the card limit' });
}

#[main]
fn main() {
  try {
      self.charge(900);
  } catch (error: obj) {
      pln(`${error.code}: ${error.reason}`);
  }
}
Output

Catch by Type​

catch (e: type) catches errors of that type. A union catches more than one, and a plain catch (or catch (e)) catches everything:

catch-types.stofPlayground ↗
#[main]
fn main() {
  try { throw(404); }
  catch (code: int | str) { pln(`caught ${code}`); }

  try { throw('timeout'); }
  catch { pln('caught something'); }
}
Output

Stof's Own Errors​

When Stof itself raises an error, like assigning to a const or calling a function that doesn't exist, the value you catch is a short error code:

error-codes.stofPlayground ↗
const plan: 'pro'

fn total(units: int) -> float { units * 2 }

#[main]
fn main() {
  try { self.plan = 'free'; }
  catch (e: str) { pln(e); }        // AssignConst

  try { self.refund(); }
  catch (e: str) { pln(e); }        // FuncDne: no such function

  try { self.total(); }
  catch (e: str) { pln(e); }        // FuncArgs: wrong arguments
}
Output

Match on these codes, not on the readable message: the codes stay the same, while messages may get better over time. The readable message is what your app and the CLI show (below).

Propagation​

An error that isn't caught moves up through each function that called the one that threw it, until something catches it. If nothing does, the call fails:

propagation.stofPlayground ↗
fn load() {
  throw('file not found');
}

fn start() {
  self.load();
}

#[main]
fn main() {
  try {
      self.start();
  } catch (message: str) {
      pln(`start failed: ${message}`);
  }
}
Output

Rethrowing​

Catch an error, add to it, and throw again:

rethrow.stofPlayground ↗
fn load_plan() {
  try {
      throw('missing price');
  } catch (message: str) {
      throw(`plan 'pro': ${message}`);
  }
}

#[main]
fn main() {
  try { self.load_plan(); }
  catch (message: str) { pln(message); }
}
Output

Errors in Your App​

An error that isn't caught inside the document makes the app's call or run fail with a readable message and the Stof call stack:

cannot multiply null: the left value is null or missing (use ?? to give a default)
at root.total (pricing.stof:4:5)
at root.main (pricing.stof:9:5)

The CLI shows the failing line too. Messages are written to be understood by people and by models, so when a model wrote the document, give the error back to it and ask for a fix. See Using Stof in Your App.

A function that throws doesn't undo what it already did, so changes made before the error stay in the document. Next, The Document Graph.