Using exception classes in Perl

Exception handling in Perl is, like OO support, very basic: die to
throw an exception, eval to catch it into the global $@
variable. What an exception is, what to do when you’ve caught it, and
other such niceties are just not part of the language.

Let’s start from the “throwing” end…

The traditional way

The simple, traditional, and excessively widespread way of signalling
failure or exceptional events (apart from returning special values
like undef) is to die with a human-readable error message. This is
sort-of fine when you don’t actually plan on catching the exception:
it gets printed to stderr, the program terminates, and that’s it.

But if you want to perform some kind of recovery when an exception is
thrown, and if what you need to do depends on exactly why it was thrown,
you have problems. Of course, you can match the string against some
regexp and decide based on that, but then you have tied the semantics
of your program to the wording of the error message, which is a user
interface detail. Things get even more complicated if you need to
extract information from the error message, such as which primary key
failed to update in a DBI exception.

A better idea: exception objects

We would like a way to throw a data structure with a recognisable
name. This is exactly what an object reference is, and die can throw any kind of scalar (although throwing a globref or a filehandle is probably a bad idea).

In addition, by using exception objects, you can group your exception
classes in a hierarchy, or even a mesh of ->isa or ->DOES.

There are several CPAN distributions of exception classes. We have
decided to use Throwable
as a base, and to add some features “stolen” from
Throwable-X. The result
is NAP::Exception.


NAP::Exception consumes Throwable and StackTrace::Auto (yes, we
almost always want a full stack trace), declares a required message
attribute, and provides an as_string method (also accessible via
overloaded stringification). as_string uses a formatter based on
String::Errf that will
replace every %{foo}s in the message with the value obtained by
calling the foo method on the exception object.

Our NAP::policy module has a special import option to set up the
calling package as a NAP::Exception subclass.

The idea is that you write:

package MyApp::Exception::FailedJob {
  use NAP::policy 'exception';
  has job_id => ( is => 'ro', required => 1 );
  has '+message' => ( default => 'Job %{job_id}d failed at %{stack_trace}s' );

package MyApp::Exception::FailedJob::DBProblem {
  use NAP::policy 'exception';
  extends 'MyApp::Exception::FailedJob';    has db_exception => ( is => 'ro', required => 1 );
  has '+message' => ( default => 'Job %{job_id}d failed because of db problems (%{db_exception}s) at %{stack_trace}s' );

And so on. Then you can either catch all ::FailedJobs, handle the
DB-caused ones differently, or just die and let the message get
printed to the user.

If you need a light-weight exception, because you know that you’ll
throw it just to catch it a few frames out, you can consume the
NAP::Exception::Role::NoStackTrace role to avoid creating a stack
trace you wouldn’t use.


After having written 3-4 exception classes, you start to understand
why the
module allows you to just declare the exceptions with very little
typing. So, we wrote something similar, a function called
simple_exception that does most of the scaffolding for you. The
above classes could then be written this way:

package MyApp::Exception {
  use NAP::policy 'simple_exception';
    'Job %{job_id}d failed at %{stack_trace}s',
    { attrs => [ 'job_id' ] }
    'Job %{job_id}d failed because of db problems (%{db_exception}s) at %{stack_trace}s',
    { extends => 'FailedJob',
      attrs => [ 'db_exception' ] }

This seems to be the bare minimum you need to write: class name,
message pattern, attribute names, and maybe a superclass. Class names
are taken to be “under” the calling package namespace, but you can
still use fully-qualified superclasses if you need to.

Catching exceptions

Of course, if all you were going to do with exceptions is to throw
them, you might as well have kept throwing strings. The power of
exception objects is evident when you start catching them.

But first, a small diversion on the various ways of catching exceptions.

Plain eval

eval { code_that_may_throw() };
if ($@) {
  if (blessed($@) and $@->isa('MyApp::Exception::FailedJob')) {
  else {
    log_errors("Something bad happened: $@");

This is the basic way of catching. It works. Mostly. In addition to
being, frankly, ugly and verbose, there are a few issues with it: $@
gets overwritten by each eval (which may well happen in a DESTROY
method, called while unwinding the stack), in some weird cases $@
might not actually be true, and a few others.


Try::Tiny fixes all the problems mentioned above, apart from some of
the ugliness:

use Try::Tiny;
try { code_that_may_throw() }
catch {
  if (blessed($_) and $_->isa('MyApp::Exception::FailedJob')) {
  else {
    log_errors("Something bad happened: $_");

You could make things a bit more legible with when and default,
but you still have to use blessed to avoid calling ->isa on a
non-object just in case something threw a string (and it will happen).


TryCatch uses the scary power of Devel::Declare to provide a very
sugary syntax (in addition to avoiding all the standard eval

use TryCatch;
try { code_that_may_throw() }
catch (MyApp::Exception::FailedJob $e) {
catch ($e) {
  log_errors("Something bad happened: $e");

It’s got its fair share of problems, though: you cannot use try as
an expression (you can with eval and Try::Tiny), return
sometimes behaves weirdly inside a catch block, and in a few of our
applications it segfaults during global destruction (which does not
affect any actual work, but makes Ops people justifiably jumpy).

At the moment, NAP::policy injects TryCatch in our packages, but
we’re working out how to move to Try::Tiny, which hides fewer

Example of use: let DBI throw our exceptions

As an interesting example of using structured exceptions, consider the
following scenario:

I have an application that can store and modify documents into
several different storage engines. Some use DBI and transactions,
some use MongoDB and optimistic concurrency control. I want to be
able to process documents regardless of the engine in use.

The basic structure of the application is:

my $iter = $storage->all_docs();
while (my ($id,$doc) = $iter->next()) {

The MongoDB storage will not do anything on ->commit(), but the
DBI may throw an exception if the transaction failed. On the other
hand, the DBI storage will never have problems on ->update because
we lock the rows when getting them, but MongoDB may detect a
concurrent modification and throw an exception.

So we rewrite our loop:

my $done = 0;
while (!$done) {
    try {
        my $iter = $storage->all_docs();
        while (my ($id,$doc) = $iter->next()) {
            try {
            } catch (MyApp::Exception::ConcurrentModification $e) {
                $doc = $storage->get_doc($id);
    } catch (MyApp::Exception::TransactionFailed $e) {

A bit more complex, but still pretty clear: keep trying until you can
commit, and re-process any document that failed to update.

Getting the MongoDB storage to throw the ConcurrentModification
exception is quite easy, since you detect that by noting that an
update affected 0 documents; we can throw it manually.

Getting DBI to throw our own kind of exceptions is… different. You
probably already know that you can get DBI to throw exceptions by
setting the RaiseError attribute on the db handle, but reading the
documentation we can see that you can also set the HandleError
attribute, to a coderef that will get passed the error message. We can
then do something like this:

sub _build_dbh {
    my ($self) = @_;
    my $dbh = DBI->connect(
            PrintError => 0,
            RaiseError => 0,
            HandleError => &_dbi_error_handler,
    return $dbh;
sub _dbi_error_handler {
    my ($message, $dbh, $ret) = @_;

    if ($message =~ m{\bduplicate key value violates unique constraint\b}) {
    elsif ($message =~ m{\bcurrent transaction is aborted\b}) {
    else {
            message => "$message at %{stack_trace}s",

And voila, DBI will throw our exceptions, and the rest of the
application does not have to deal with trying to parse error strings
or wondering which storage engine it’s using.

For a more comprehensive solution, see DBIx::Error.

Print Friendly
This entry was posted in Perl by dakkar. Bookmark the permalink.

About dakkar

Gianni is a Perl Architect at NAP. His code from previous lives runs in universities administration software, inside news system, and even in Antarctica. He's currently busy writing libraries to make "the right thing" be "the easy thing".

2 thoughts on “Using exception classes in Perl

  1. A good programs contains a large number of exceptions: conditions which disrupt the usual flow. Not rarely about 1 per 4 lines of logic. Either you combine many errors into one exception (less clear), or you have a lot of exceptions to program (and test). Besides, you often get into the difficulty of maintaining an exception hierarchy. Maintaining hierarchies with many components is quite hard.

    An alternative is to use tags in stead of classes. For instance, in Log::Report, an (user-)error exception is thrown like this: (includes delayed optional translation)

    @files >= 3
    or error __x”three files are needed, I got {count}”, count => scalar @files,
    _class => ‘user,show_help, unrecoverable’;

    IMHO, the lighter the syntax for exceptions is, the better the error reporting gets. During YAPC::EU, Moritz spoke about the new Perl6 exception system, and that a number old errors still had to be translated to the new system. When the syntax is light, it is a no-brainer.

    I do not like classes in a program which are only rarely used, for a kind of singleton objects. It would also be possible to create a set of exception classes (for instance in the “use warnings” category) as base, and then use tags on top of those.

Leave a Reply