One way of handling errors in OCaml is exceptions. The standard library relies heavily upon them.
Exceptions belong to the type
exn (an extensible sum type):
exception Foo of string let i_will_fail () = raise (Foo "Oh no!")
Here, we add a variant
Foo to the type
exn, and create a function
that will raise this exception. Now, how do we handle exceptions?
The construct is
try ... with ...:
let safe_inverse n = try Some (1 / n) with Division_by_zero -> None let safe_list_find p l = try Some (List.find p l) with Not_found -> None
We can try those functions:
# 1 / 0;; Exception: Division_by_zero. # safe_inverse 2;; - : int option = Some 0 # safe_inverse 0;; - : int option = None # List.find (fun x -> x mod 2 = 0) [1; 3; 5];; Exception: Not_found. # safe_list_find (fun x -> x mod 2 = 0) [1; 3; 4; 5];; - : int option = Some 4 # safe_list_find (fun x -> x mod 2 = 0) [1; 3; 5];; - : int option = None
The biggest issue with exceptions is that they do not appear in types.
One has to read the documentation to see that, indeed,
List.hd are not total functions, and that they might fail.
It is considered good practice nowadays, when a function can fail in
cases that are not bugs (i.e., not
assert false, but network failures,
keys not present, etc.)
to return a more explicit type such as
'a option or
('a, 'b) result.
A relatively common idiom is to have such a safe version of the function,
val foo : a -> b option, and an exception raising
val foo_exn : a -> b.
Functions that can raise exceptions should be documented like this:
val foo : a -> b (** foo does this and that, here is how it works, etc. @raise Invalid_argument if [a] doesn't satisfy ... @raise Sys_error if filesystem is not happy *)
To get a stacktrace when a unhandled exception makes your program crash, you
need to compile the program in "debug" mode (with
-g when calling
-tag 'debug' when calling
OCAMLRUNPARAM=b ./myprogram [args]
And you will get a stacktrace. Alternatively, you can call, from within the program,
let () = Printexc.record_backtrace true
To print an exception, the module
Printexc comes in handy. For instance,
the following function
notify_user : (unit -> 'a) -> 'a can be used
to call a function and, if it fails, print the exception on
If stacktraces are enabled, this function will also display it.
let notify_user f = try f () with e -> let msg = Printexc.to_string e and stack = Printexc.get_backtrace () in Printf.eprintf "there was an error: %s%s\n" msg stack; raise e
OCaml knows how to print its built-in exception, but you can also tell it how to print your own exceptions:
exception Foo of int let () = Printexc.register_printer (function | Foo i -> Some (Printf.sprintf "Foo(%d)" i) | _ -> None (* for other exceptions *) )
Each printer should take care of the exceptions it knows about, returning
Some <printed exception>, and return
None otherwise (let the other printers
do the job!).
The Stdlib module contains the following type:
type ('a, 'b) result = | Ok of 'a | Error of 'b
Ok x means that the computation succeeded with
Error e means that it failed.
Pattern matching can be used to deal with both cases, as with any
other sum type. The advantage here is that a function
a -> b that
fails can be modified so its type is
a -> (b, error) result,
which makes the failure explicit.
The error case
Error e can be of any type
'b type variable), but a few possible choices
exn, in which case the result type just makes exceptions explicit.
string, where the error case is a message that indicates what failed.
string Lazy.t, a more elaborate form of error message that is only evaluated if printing is required.
- some polymorphic variant, with one case per possible error. This is very accurate (each error can be dealt with explicitly and occurs in the type) but the use of polymorphic variants sometimes make error messages hard to read.
For easy combination of functions that can fail, many alternative standard
libraries provide useful combinators on the
assert takes an expression as an argument and throws an
exception if the provided expression evaluates to
Assuming that you don't catch this exception (it's probably
unwise to catch this exception, particularly for beginners), this
results in the program stopping and printing out the source file and
line number where the error occurred. An example:
# assert (Sys.os_type = "Win32");; Exception: Assert_failure ("//toplevel//", 1, 1). Called from Stdlib__Fun.protect in file "fun.ml", line 33, characters 8-15 Re-raised at Stdlib__Fun.protect in file "fun.ml", line 38, characters 6-52 Called from Topeval.load_lambda in file "toplevel/byte/topeval.ml", line 89, characters 4-150
(Running this on Win32, of course, won't throw an error).
You can also just call
assert false to stop your program if things
just aren't going well, but you're probably better to use ...
failwith "error message" throws a
Failure exception, which again
assuming you don't try to catch it, will stop the program with the given
failwith is often used during pattern matching, like
this real example:
match Sys.os_type with | "Unix" | "Cygwin" -> (* code omitted *) | "Win32" -> (* code omitted *) | "MacOS" -> (* code omitted *) | _ -> failwith "this system is not supported"
Note a couple of extra pattern matching features in this example too. A
so-called "range pattern" is used to match either
"Cygwin", and the special
_ pattern which matches "anything else".
Help Improve Our Documentation
All OCaml docs are open source. See something that's wrong or unclear? Submit a pull request.Contribute