Skip to content

Error Handling

There are two concepts used in Tamarin for dealing with situations where something goes wrong: errors and results. A Tamarin object type is used for each of these, object.Error and object.Result. There are various built-in functions and methods used to interact with these as values to design an error resilient application.

In short, when an error object is generated, the Tamarin interpreter recognizes the error, evaluation of the code stops, and the error is returned. This means that, by default, a Tamarin program halts on an error.

Results are objects that may contain an ok value or an err value. These are returned from operations that have common error conditions, such as I/O operations that may fail due to network problems or similar. These result objects offer methods to test if the result is ok or err and then the developer can decide how the application should handle each of those cases.

The built-in function try can be used to work with both errors and results. It allows the developer to return a fallback value when an expression evaluates to an error or an err result.


Generate an error intentionally using the error built-in function. This stops evaluation of the Tamarin program immediately:

>>> error("kaboom")

Wrap an operation with try to prevent an error from propagating:

>>> try(error("kaboom"), "that failed")
"that failed"


Create a result containing an error message using the err built-in function. This result is treated as any other value in Tamarin:

>>> e := err("io problem")
err("io problem")
>>> type(e)
>>> e.is_err()
>>> e.err_msg()
"io problem"

Like with errors, the try function works with results:

>>> try(err("io problem"), "fallback value")
"fallback value"

Successful results are instead created with the ok built-in function:

>>> res := ok("result-value")
>>> res.unwrap()
>>> res.is_err()
>>> res.is_ok()

The try function returns ok results as-is:

>>> res := ok("result-value")
>>> try(res, "fallback value")


Results containing an ok value proxy to the wrapped value. This is a convenience for scripting situations to avoid needing to explicitly unwrap the result. If this is attempted with an err result, an error is generated that stops execution.

This example shows how the result proxies to the map.keys method:

>>> res := ok({foo: "bar"})
ok({"foo": "bar"})
>>> res.keys()
>>> m := res.unwrap()
{"foo": "bar"}
>>> m.keys()


A fallback function can be provided as the second argument to try:

>>> e := err("nope")
>>> try(e, func(msg) { print('operation failed: {msg}') })
operation failed: nope


The JSON module is designed to return result values for operations that may fail:

>>> json.unmarshal("true")
>>> json.unmarshal("invalid-json")
err("value error: json.unmarshal failed with: invalid character 'i' looking for beginning of value")