Catalyst::Manual::Tutorial::Debugging - Catalyst Tutorial - Part 6: Debugging


This is Part 6 of 9 for the Catalyst tutorial.

Tutorial Overview

  1. Introduction

  2. Catalyst Basics

  3. Basic CRUD

  4. Authentication

  5. Authorization

  6. Debugging

  7. Testing

  8. AdvancedCRUD

  9. Appendices


This part of the tutorial takes a brief look at the primary options available for troubleshooting Catalyst applications.

Note that when it comes to debugging and troubleshooting, there are two camps:

  • Fans of log and print statements embedded in the code.

  • Fans of interactive debuggers.

Catalyst is able to easily accommodate both styles of debugging.


Folks in the former group can use Catalyst's $c->log facility. (See Catalyst::Log for more detail.) For example, if you add the following code to a controller action method:

    $c->log->info("Starting the foreach loop here");

    $c->log->debug("Value of $id is: ".$id);

Then the Catalyst development server will display your message along with the other debug output. To accomplish the same thing in a TTSite view use:

    [% Catalyst.log.debug("This is a test log message") %]

You can also use Data::Dumper in both Catalyst code (use Data::Dumper; $c->log->debug("$var is: ".Dumper($var));)) and TT templates ([% Dumper.dump(book) %].


Members of the interactive-debugger fan club will also be at home with Catalyst applications. One approach to this style of Perl debugging is to embed breakpoints in your code. For example, open lib/MyApp/Controller/ in your editor and add the DB::single=1 line as follows inside the list method (I like to "left-justify" my debug statements so I don't forget to remove them, but you can obviously indent them if you prefer):

    sub list : Local {
        # Retrieve the usual perl OO '$self' for this object. $c is the Catalyst
        # 'Context' that's used to 'glue together' the various components
        # that make up the application
        my ($self, $c) = @_;
        # Retrieve all of the book records as book model objects and store in the
        # stash where they can be accessed by the TT template
        $c->stash->{books} = [$c->model('MyAppDB::Book')->all];
        # Set the TT template to use.  You will almost always want to do this
        # in your action methods.
        $c->stash->{template} = 'books/list.tt2';

This causes the Perl Debugger to enter "single step mode" when this command is encountered (it has no effect when Perl is run without the -d flag).

To now run the Catalyst development server under the Perl debugger, simply prepend perl -d to the front of script/

    $ perl -d script/

This will start the interactive debugger and produce output similar to:

    $ perl -d script/  
    Loading DB routines from version 1.27
    Editor support available.
    Enter h or `h h' for help, or `man perldebug' for more help.
    main::(script/      my $debug         = 0;

Press the c key and hit Enter to continue executing the Catalyst development server under the debugger. Although execution speed will be slightly slower than normal, you should soon see the usual Catalyst startup debug information.

Now point your browser to http://localhost:3000/books/list and log in. Once the breakpoint is encountered in the MyApp::Controller::list method, the console session running the development server will drop to the Perl debugger prompt:

    40:         $c->stash->{books} = [$c->model('MyAppDB::Book')->all];

You now have the full Perl debugger at your disposal. First use the next feature by typing n to execute the all method on the Book model (n jumps over method/subroutine calls; you can also use s to single-step into methods/subroutines):

      DB<1> n
    SELECT, me.authors, me.title, me.rating FROM books me:
    44:         $c->stash->{template} = 'books/list.tt2';

This takes you to the next line of code where the template name is set. Notice that because we enabled DBIX_CLASS_STORAGE_DBI_DEBUG=1 earlier, SQL debug output also shows up in the development server debug output.

Next, list the methods available on our Book model:

      DB<1> m $c->model('MyAppDB::Book')
    <lines removed for brevity>

We can also play with the model directly:

      DB<2> x ($c->model('MyAppDB::Book')->all)[1]->title
    SELECT, me.title, me.rating FROM books me:
    0  'TCP/IP Illustrated, Volume 1'

This uses the Perl debugger x command to display the title of a book.

Next we inspect the books element of the Catalyst stash (the 4 argument to the x command limits the depth of the dump to 4 levels):

      DB<3> x 4 $c->stash->{books}
    0  ARRAY(0xa8f3b7c)
       0  MyApp::Model::MyAppDB::Book=HASH(0xb8e702c)
          '_column_data' => HASH(0xb8e5e2c)
             'id' => 1
             'rating' => 5
             'title' => 'CCSP SNRS Exam Certification Guide'
          '_in_storage' => 1
    <lines removed for brevity>

Then enter the c command to continue processing until the next breakpoint is hit (or the application exits):

      DB<4> c
    SELECT, author.first_name, author.last_name FROM ...

Finally, press Ctrl+C to break out of the development server. Because we are running inside the Perl debugger, you will drop to the debugger prompt. Press q to exit the debugger and return to your OS shell prompt:

      DB<4> q

For more information on using the Perl debugger, please see perldebug and perldebtut. You can also type h or h h at the debugger prompt to view the built-in help screens.


Kennedy Clark,

Please report any errors, issues or suggestions to the author.

Copyright 2006, Kennedy Clark, under Creative Commons License (

Version: .94