OCaml Module 8 – Errors, input/output and command-line programs
Exceptions and resource cleanup
Raise and handle OCaml exceptions, define your own with inline records, close files safely with Fun.protect and with_open, and read backtraces.
What you will learn
- Define and raise exceptions with inline records
- Handle exceptions with try-with and match-exception
- Protect resources safely with Fun.protect and In_channel.with_open_text
- Trace errors by reading backtraces for debugging
Before you start
What you’ll learn · Before you start
What you will learn
- Define and raise exceptions with inline records
- Handle exceptions with try-with and match-exception
- Protect resources safely with Fun.protect and In_channel.with_open_text
- Trace errors by reading backtraces for debugging
Before you start
On this page
A file-reading function opens a channel, reads a line and closes the channel. When the file is empty, input_line raises End_of_file before close_in runs, and the channel stays open. Call the function 100 times on a system that allows 32 open files per process, and the 30th call fails.
You will define and raise exception: A value that travels up the call stack until a handler catches it or the program stops, carrying the name and details of a failure. with inline records, handle them with try ... with and match ... with exception, close resources safely with Fun.protect and In_channel.with_open_text, and read backtrace: A record of the call stack at the point where an exception was raised, showing which functions were active and where. for debugging.
An exception breaks normal flow and carries data
An exception is a value that travels up the call stack until a handler catches it or the program stops. The standard library raises Not_found when a search finds nothing, Invalid_argument when an argument makes no sense, Failure when a function is undefined on its argument, such as int_of_string "12O", and End_of_file when a read reaches the end. Many raising functions have an _opt twin, such as List.assoc_opt and int_of_string_opt, that returns None instead. Not all do: String.sub has no _opt form, so its caller checks the range before the call.
from session import toplevel
# The standard library's own failures: Not_found for a missing key, Invalid_argument for an argument outside what the
# function accepts, Failure for input it cannot read, each beside the _opt function that returns an option instead.
# Then assert, and an exception used to leave a loop early with raise_notrace.
toplevel("""
let pins = [("Pune", "411001"); ("Kochi", "682001")];;
List.assoc "Delhi" pins;;
List.assoc_opt "Delhi" pins;;
String.sub "MySmartCoPilot" 2 40;;
int_of_string "12O";;
int_of_string_opt "12O";;
List.nth [10; 20; 30] 5;;
List.nth_opt [10; 20; 30] 5;;
assert (List.length pins = 3);;
exception Found of int;;
let first_negative a =
try Array.iteri (fun i x -> if x < 0 then raise_notrace (Found i)) a; None
with Found i -> Some i;;
first_negative [| 3; 1; -4; 1; -5 |];;
""")Output
$ ocaml
OCaml version 5.5.1
Enter #help;; for help.
# let pins = [("Pune", "411001"); ("Kochi", "682001")];;
val pins : (string * string) list = [("Pune", "411001"); ("Kochi", "682001")]
# List.assoc "Delhi" pins;;
Exception: Not_found.
# List.assoc_opt "Delhi" pins;;
- : string option = None
# String.sub "MySmartCoPilot" 2 40;;
Exception: Invalid_argument "String.sub / Bytes.sub".
# int_of_string "12O";;
Exception: Failure "int_of_string".
# int_of_string_opt "12O";;
- : int option = None
# List.nth [10; 20; 30] 5;;
Exception: Failure "nth".
# List.nth_opt [10; 20; 30] 5;;
- : int option = None
# assert (List.length pins = 3);;
Exception: Assert_failure ("//toplevel//", 1, 0).
# exception Found of int;;
exception Found of int
# let first_negative a =
try Array.iteri (fun i x -> if x < 0 then raise_notrace (Found i)) a; None
with Found i -> Some i;;
val first_negative : int array -> int option = <fun>
# first_negative [| 3; 1; -4; 1; -5 |];;
- : int option = Some 2
Recorded with Python 3.14.8 on macOS 26 arm64. To run it yourself: mise exec python@3.14.8 -- python3 conventions_session.py
assert checks a condition and raises Assert_failure when it is false. raise_notrace raises without recording a backtrace, useful when an exception is used for control flow, such as leaving a loop early with a Found exception.
Key idea
An exception names a failure and carries its details; a handler decides what to do with it.
Checkpoint
Check: Raising and handling exceptions
Define your own exceptions with inline records
An exception defined with exception is a first-class value. Add an of clause to carry data. An inline record puts the fields right in the definition and lets the handler name them directly. Inline records arrived in OCaml 4.03; before that, an exception could carry a record only by naming a record type declared on its own.
from session import toplevel
# A wallet's withdraw function signals two failures with exceptions: a domain exception whose inline record says how
# much was needed and how much was there, and the standard Invalid_argument for an amount that makes no sense. The
# handlers use match ... with exception, then the older try ... with on the same calls.
toplevel("""
exception Insufficient_funds of { needed : int; available : int };;
let withdraw balance amount =
if amount <= 0 then invalid_arg "withdraw: amount must be positive"
else if amount > balance then raise (Insufficient_funds { needed = amount; available = balance })
else balance - amount;;
withdraw 500 200;;
withdraw 500 800;;
let describe balance amount =
match withdraw balance amount with
| left -> Printf.sprintf "paid %d, %d left" amount left
| exception Insufficient_funds { needed; available } -> Printf.sprintf "short by %d" (needed - available)
| exception Invalid_argument message -> message;;
List.map (describe 500) [200; 800; 0];;
let describe_try balance amount =
try Printf.sprintf "paid %d, %d left" amount (withdraw balance amount) with
| Insufficient_funds r -> Printf.sprintf "short by %d" (r.needed - r.available);;
describe_try 500 800;;
describe_try 500 0;;
""")Output
$ ocaml
OCaml version 5.5.1
Enter #help;; for help.
# exception Insufficient_funds of { needed : int; available : int };;
exception Insufficient_funds of { needed : int; available : int; }
# let withdraw balance amount =
if amount <= 0 then invalid_arg "withdraw: amount must be positive"
else if amount > balance then raise (Insufficient_funds { needed = amount; available = balance })
else balance - amount;;
val withdraw : int -> int -> int = <fun>
# withdraw 500 200;;
- : int = 300
# withdraw 500 800;;
Exception: Insufficient_funds {needed = 800; available = 500}.
# let describe balance amount =
match withdraw balance amount with
| left -> Printf.sprintf "paid %d, %d left" amount left
| exception Insufficient_funds { needed; available } -> Printf.sprintf "short by %d" (needed - available)
| exception Invalid_argument message -> message;;
val describe : int -> int -> string = <fun>
# List.map (describe 500) [200; 800; 0];;
- : string list =
["paid 200, 300 left"; "short by 300"; "withdraw: amount must be positive"]
# let describe_try balance amount =
try Printf.sprintf "paid %d, %d left" amount (withdraw balance amount) with
| Insufficient_funds r -> Printf.sprintf "short by %d" (r.needed - r.available);;
val describe_try : int -> int -> string = <fun>
# describe_try 500 800;;
- : string = "short by 300"
# describe_try 500 0;;
Exception: Invalid_argument "withdraw: amount must be positive".
Recorded with Python 3.14.8 on macOS 26 arm64. To run it yourself: mise exec python@3.14.8 -- python3 withdraw_session.py
Insufficient_funds { needed; available } says exactly what went wrong. The handler pattern-matches on the exception and on its fields: exception Insufficient_funds { needed; available } binds both at once. match ... with exception checks exceptions and results in one pattern match; try ... with is the older form that catches only exceptions.
Tip
Use match ... with exception when you handle both a result and an exception from the same call. Use try ... with when the work spans several statements or when you want to catch an exception from any of them.
Checkpoint
Check: Defining exceptions with inline records
A leaked channel exhausts file descriptors
When code between opening and closing a channel raises an exception, the close never runs, and nothing closes the channel later. The garbage collector may free the channel’s memory, but it leaves the file descriptor open until the process ends; run a program with OCAMLRUNPARAM=W and the runtime warns about each channel that dies without being closed. Under a low limit on open files the leak shows within a second, so the session below sets the limit to 32 with ulimit -n 32.
from session import files, run
# leak.ml closes its file only when input_line succeeds; no_leak.ml lets In_channel.with_open_text close it. Both read
# an empty file 100 times under a limit of 32 open files per process (ulimit -n 32), so a leak shows within the run.
files("leak.ml", "no_leak.ml")
run(
"""
: > empty.txt
ocamlopt leak.ml -o leak
ocamlopt no_leak.ml -o no_leak
ulimit -n 32
./leak
./no_leak
"""
)Output
$ : > empty.txt $ ocamlopt leak.ml -o leak $ ocamlopt no_leak.ml -o no_leak $ ulimit -n 32 $ ./leak call 30 failed: Sys_error "empty.txt: Too many open files" $ ./no_leak 100 calls, no error
Recorded with Python 3.14.8 on macOS 26 arm64. To run it yourself: mise exec python@3.14.8 -- python3 leak_session.py
The first version opens empty.txt, calls input_line (which raises End_of_file), and never reaches close_in. The 30th call fails with Sys_error "empty.txt: Too many open files": standard input, output and error hold 3 of the 32 descriptors, and 29 leaked channels hold the rest. The second version wraps the read in In_channel.with_open_text, which closes the channel whether the function returns or raises, and finishes all 100 calls.
Key idea
A resource that must be released belongs inside with_open_text, with_open_bin or Fun.protect, not between an open and a close that an exception can skip.
Checkpoint
Check: Resource cleanup with Fun.protect
Fun.protect runs cleanup whether work succeeds or raises
Fun.protect ~finally work calls work (), then finally (), and returns or re-raises what work did. The cleanup runs even when an exception unwinds the stack. If finally itself raises, its exception arrives wrapped in Fun.Finally_raised so it cannot be mistaken for an exception of work. The ~finally function takes no arguments; it runs for its side effect only.
from session import toplevel
# Fun.protect ~finally work calls work (), then finally (), whether work returned or raised, and passes on work's
# result or exception. The log records the order. When finally itself raises, its exception arrives wrapped in
# Fun.Finally_raised, so it cannot be mistaken for an exception of work.
toplevel("""
let log = ref [];;
let note s = log := s :: !log;;
let finally () = note "finally: release";;
Fun.protect ~finally (fun () -> note "work: returns 42"; 42);;
(try Fun.protect ~finally (fun () -> note "work: raises"; failwith "disk full")
with Failure m -> note ("caller: caught " ^ m); 0);;
List.rev !log;;
Fun.protect ~finally:(fun () -> failwith "close failed") (fun () -> 42);;
Fun.protect ~finally:(fun () -> failwith "close failed") (fun () -> failwith "disk full");;
""")Output
$ ocaml
OCaml version 5.5.1
Enter #help;; for help.
# let log = ref [];;
val log : '_weak1 list ref = {contents = []}
# let note s = log := s :: !log;;
val note : '_weak1 -> unit = <fun>
# let finally () = note "finally: release";;
val finally : unit -> unit = <fun>
# Fun.protect ~finally (fun () -> note "work: returns 42"; 42);;
- : int = 42
# (try Fun.protect ~finally (fun () -> note "work: raises"; failwith "disk full")
with Failure m -> note ("caller: caught " ^ m); 0);;
- : int = 0
# List.rev !log;;
- : string list =
["work: returns 42"; "finally: release"; "work: raises"; "finally: release";
"caller: caught disk full"]
# Fun.protect ~finally:(fun () -> failwith "close failed") (fun () -> 42);;
Exception: Fun.Finally_raised: Failure("close failed")
# Fun.protect ~finally:(fun () -> failwith "close failed") (fun () -> failwith "disk full");;
Exception: Fun.Finally_raised: Failure("close failed")
Recorded with Python 3.14.8 on macOS 26 arm64. To run it yourself: mise exec python@3.14.8 -- python3 protect_session.py
The log records the order: work runs first, then finally, then the caller catches the exception. The last two lines show what happens when finally raises: the call ends with Fun.Finally_raised around the cleanup’s Failure("close failed"), whether work returned 42 or raised Failure "disk full", and the exception of work is lost. The documentation of Fun calls a raising finally a programming error, so a cleanup that can fail handles its own exceptions. Reach for Fun.protect when the resource is not a channel: a lock, a temporary file or a connection.
Common mistake
Pass Fun.protect the function, not its result. Fun.protect ~finally (work ()) is rejected unless work () itself returns a function: protect expects a value of type unit -> 'a, and the compiler’s hint asks whether you forgot to wrap the expression in fun () ->. Write Fun.protect ~finally work or Fun.protect ~finally (fun () -> work ()).
Checkpoint
Check: Resource cleanup with Fun.protect
A backtrace shows where the exception was raised
An uncaught exception prints its message and stops the program with exit status: An integer a program returns to its parent process when it ends, where 0 means success and other values indicate failures. 2; by default no call stack is shown. Setting OCAMLRUNPARAM=b asks the runtime for a backtrace, but a program compiled without -g holds no location information, so every frame reads unknown location. Recompiling with -g makes the same request print the call stack with file names and line numbers.
from session import files, run
# amounts.ml stops with an uncaught Failure. Compiled to bytecode without -g, OCAMLRUNPARAM=b can only ask for a
# backtrace with no location information ("unknown location"); recompiled with -g, the same request prints the call
# stack with file names and lines.
files("amounts.ml")
run(
"""
cat amounts.ml
ocamlc amounts.ml -o amounts
!OCAMLRUNPARAM=b ./amounts
ocamlc -g amounts.ml -o amounts
!OCAMLRUNPARAM=b ./amounts
"""
)Output
$ cat amounts.ml
(* total adds the amounts of a list of lines. One line has the letter O where a zero belongs, so parse_amount raises
Failure, nothing handles it, and the program stops. *)
let parse_amount line =
match int_of_string_opt line with
| Some n -> n
| None -> failwith ("not an amount: " ^ line)
let total lines = List.fold_left (fun sum line -> sum + parse_amount line) 0 lines
let () = Printf.printf "total %d\n" (total [ "120"; "80"; "12O" ])
$ ocamlc amounts.ml -o amounts
$ OCAMLRUNPARAM=b ./amounts
Fatal error: exception Failure("not an amount: 12O")
Called from unknown location (inlined)
Called from unknown location (inlined)
Called from unknown location (inlined)
[exit status 2]
$ ocamlc -g amounts.ml -o amounts
$ OCAMLRUNPARAM=b ./amounts
Fatal error: exception Failure("not an amount: 12O")
Raised at Stdlib.failwith in file "stdlib.ml", line 29, characters 17-33
Called from Amounts.total.(fun) in file "amounts.ml", line 8, characters 56-73
Called from Stdlib__List.fold_left in file "list.ml", line 125, characters 24-34
Called from Amounts in file "amounts.ml", line 10, characters 36-66
[exit status 2]
Recorded with Python 3.14.8 on macOS 26 arm64. To run it yourself: mise exec python@3.14.8 -- python3 backtrace_session.py
A custom exception can carry its own readable message and record its backtrace from code, without any environment variable. Register a printer with Printexc.register_printer, then call Printexc.record_backtrace true and Printexc.print_backtrace.
from session import files, run
# printer.ml registers a printer for its own exception and records and prints the backtrace from code with Printexc,
# so it needs neither OCAMLRUNPARAM nor a caller. Compiled with -g so the backtrace carries file and line numbers.
files("printer.ml")
run(
"""
cat printer.ml
ocamlc -g printer.ml -o printer
!./printer
"""
)Output
$ cat printer.ml
(* A custom exception gets a readable message from Printexc.register_printer, and the program records and prints the
backtrace itself with Printexc.record_backtrace and Printexc.print_backtrace, without OCAMLRUNPARAM. *)
exception Insufficient_funds of { needed : int; available : int }
let () =
Printexc.register_printer (function
| Insufficient_funds { needed; available } ->
Some (Printf.sprintf "Insufficient_funds: needed %d, available %d" needed available)
| _ -> None)
let withdraw balance amount =
if amount > balance then raise (Insufficient_funds { needed = amount; available = balance });
balance - amount
let () =
Printexc.record_backtrace true;
match withdraw 500 800 with
| left -> Printf.printf "%d left\n" left
| exception e ->
prerr_endline ("error: " ^ Printexc.to_string e);
Printexc.print_backtrace stderr;
exit 1
$ ocamlc -g printer.ml -o printer
$ ./printer
error: Insufficient_funds: needed 800, available 500
Raised at Printer.withdraw in file "printer.ml", line 12, characters 27-94
Called from Printer in file "printer.ml", line 17, characters 8-24
[exit status 1]
Recorded with Python 3.14.8 on macOS 26 arm64. To run it yourself: mise exec python@3.14.8 -- python3 printer_session.py
Tip
For a long-running program, call Printexc.record_backtrace true at startup and log Printexc.get_backtrace () in the top-level handler, so a crash report names the line that raised. Build it with -g as well, or the report has no file names and line numbers to show.
Checkpoint
Check: Backtraces for debugging
Practice
Practice that adapts to you
Practise this lesson
7 questions about 4 ideas of this lesson. Each answer is explained at once, and what you get right is kept in this browser.
Interview questions
What is the difference between List.assoc and List.assoc_opt?
List.assoc raises Not_found when the key is missing; List.assoc_opt returns None instead. Reach for the _opt variant when a missing key is an expected outcome rather than an error, and keep the raising form for a lookup that should never fail.
Model answers open with any pass: ₹79 for 1 week ($2.99), one payment that never renews.
-
Fresher to senior
How do you ensure a file channel is closed whether a function succeeds or raises an exception?
-
Mid to staff
Why would you define an exception with an inline record instead of a tuple?
Flashcards · 8 cards
Recall it, then check
Say the answer to yourself before you look: recalling it is what makes it stick.
-
What does an exception do to a running OCaml program?
It breaks normal flow, names a failure and carries its details; a handler decides what happens next.
-
How does your own exception carry several named details?
With an inline record in its definition, such as exception Insufficient_funds of { needed : int; available : int }, so the handler can name the fields directly. Inline records arrived in OCaml 4.03.
-
Why does a reader that opens a channel, calls input_line and then close_in leak on an empty file?
input_line raises End_of_file before close_in runs, so the channel stays open; the descriptor is not released until the process ends.
-
Where should a resource that must be released live?
Inside In_channel.with_open_text, with_open_bin or Fun.protect, never between an open and a close that an exception can skip.
-
Why is Fun.protect ~finally (work ()) rejected?
Fun.protect expects a value of type unit -> 'a, not the result of the work. Write Fun.protect ~finally work or Fun.protect ~finally (fun () -> work ()).
-
How do you get a backtrace that names the line that raised?
Compile with -g and run with OCAMLRUNPARAM=b, or call Printexc.record_backtrace true at start-up and log Printexc.get_backtrace () in the top-level handler.
-
When is match … with exception the better form, and when try … with?
match … with exception when you handle both a result and an exception of the same call; try … with when the work spans several statements and an exception from any of them should be caught.
-
When should code use List.assoc_opt rather than List.assoc?
When a missing key is an expected outcome: assoc_opt returns None instead of raising Not_found. Keep the raising form for a lookup that should never fail.
Key takeaways
- An exception names a failure and carries its details; a handler decides what to do with it.
- Define your own exceptions with inline records to carry structured data.
- Wrap resources that must be released in
with_open_text,with_open_binorFun.protect, not between open and close. - Compile with
-gand run withOCAMLRUNPARAM=bto see backtraces; register a printer for custom exceptions. - Use
match ... with exceptionwhen you handle both a result and an exception from the same call.
Terms in this lesson
- backtrace
- A record of the call stack at the point where an exception was raised, showing which functions were active and where.
- exception
- A value that travels up the call stack until a handler catches it or the program stops, carrying the name and details of a failure.
- exception handler
- A try-with or match-with-exception clause that intercepts an exception and decides what to do with it instead of letting it propagate.
- exit status
- An integer a program returns to its parent process when it ends, where 0 means success and other values indicate failures.
References
- The OCaml Manual: Exceptions (Inria and the OCaml developers)
- The OCaml Manual: module Fun (Inria and the OCaml developers)
- The OCaml Manual: module In_channel (Inria and the OCaml developers)
- The OCaml Manual: module Printexc (Inria and the OCaml developers)
- The OCaml Manual: module Stdlib (Inria and the OCaml developers)
- The OCaml Manual: The runtime system (ocamlrun) (Inria and the OCaml developers)
- The OCaml Manual: Inline records (Inria and the OCaml developers)
- POSIX.1-2024: Exit status (IEEE and The Open Group)
Report a problem with this lesson
Kept only in this browser. Your Learn progress