Debugging Catalyst Applications

For an introduction to Catalyst debugging, see Catalyst::Manual::Tutorial::Debugging.

A debugging config file

You may wish to run your application in debug mode with a different configuration file (e.g. specifying a test database). To tell the Config::Loader used by your app to load a different config file, set the MYAPP_CONFIG environment variable:

FOOAPP_CONFIG=fooapp_sqlite.conf script/ -d

Displaying debug info

To get a variable dump in the browser, append ?dump_info=1 at the end of the URL while you run the server in debug mode (-d).

Debugging with ActiveState Komodo

Debugging "live" Catalyst applications is possible with Komodo and might work with Eclipse+EPIC (please chip in if you have experience with the latter).

You don't want to step through all the Catalyst-specific code. Put a breakpoint (F9 in Komodo) directly in the file you wish to start debugging from (most of the time, a controller). Alternatively, you can insert $DB::single = 1 statements where you want breakpoints in your application.

Then, call perl with the -d flag to enable debugging:

perl -d script/

You can also debug how your application handles a request without running an HTTP server. To do this, run the script, or any of the .t scripts. They all use Catalyst::Test:

perl -d /troublemaker_url/foo

Debugging remotely with Komodo

To debug remotely with Komodo, refer to ActiveState's article on Remote Debugging Perl with Komodo. In short, here's what to do:

  1. wget and unpack the perl debugging lib tgz

  2. add the following to your ~/.profile:

    export PERL5LIB=/path/to/where/you/unpacked/the/tgz
    export PERLDB_OPTS="RemotePort=[IP of the Komodo machine]:9000"
  3. on the remote host, run

    perl -d

Komodo will pop-up on your "Komodo machine" and ask to map the file ("Mapped URIs") to a Remote Account (Preferences -> Servers).

If the remote host can't connect to your Komodo machine (e.g. due to a firewall), you can do the following:

  1. Replace the <IP of the Komodo machine> above with
  2. Setup an SSH connection from your debugging machine to your remote server and define the following S2C (server-to-client) forwarding rule: to localhost:9000. For Windows, an excellent SSH client that supports both client-to-server and server-to-client forwarding is Bitvise Tunnelier.


There are/were two issues with Komodo:

  1. (fixed in Komodo 5.1.3 or earlier) Komodo couldn't step past the while ( accept( Remote, $daemon ) ) loop in Catalyst::Engine::HTTP.
  2. Stepping through scripts that use Catalyst::Test causes the following error message to be dumped in Komodo's Output pane:

    Unexpected use of a standard filehandle while debugging:
    The STDOUT and STDERR handles have been tied for remote debugging, 
    and can't be redirected in the code being debugged.
    Try adding 
      untie(*STDOUT) if tied(*STDOUT);
      untie(*STDERR) if tied(*STDERR);
    to the code at /usr/lib/perl5/site_perl/5.8/HTTP/Request/ line 124

This is currently tracked on ActiveState's Bugzilla queue for Komodo.

Using perl's integrated debugger

Alternatively, you can debug using perl's integrated debugger:

Debugging HTTP traffic between your browser and Catalyst

Debugging database queries

If you're using DBIx::Class, set DBIC_TRACE=1 when running your application.

See also