Graham Knop > Devel-Confess > Devel::Confess



Annotate this POD


Open  0
View/Report Bugs
Module Version: 0.009002   Source  


Devel::Confess - Include stack traces on all warnings and errors


Use on the command line:

  # Make every warning and error include a full stack trace
  perl -d:Confess

  # Also usable as a module
  perl -MDevel::Confess

  # display warnings in yellow and errors in red
  perl -d:Confess=color

  # set options by environment
  export DEVEL_CONFESS_OPTIONS='color dump'
  perl -d:Confess

Can also be used inside a script:

  use Devel::Confess;

  use Devel::Confess 'color';

  # disable stack traces
  no Devel::Confess;


This module is meant as a debugging aid. It can be used to make a script complain loudly with stack backtraces when warn()ing or die()ing. Unlike other similar modules (e.g. Carp::Always), stack traces will also be included when exception objects are thrown.

The stack traces are generated using Carp, and will work for all types of errors. Carp's carp and croak functions will also be made to include stack traces.

  # it works for explicit die's and warn's
  $ perl -d:Confess -e 'sub f { die "arghh" }; sub g { f }; g'
  arghh at -e line 1.
          main::f() called at -e line 1
          main::g() called at -e line 1

  # it works for interpreter-thrown failures
  $ perl -d:Confess -w -e 'sub f { $a = shift; @a = @$a };' \
                                        -e 'sub g { f(undef) }; g'
  Use of uninitialized value $a in array dereference at -e line 1.
          main::f(undef) called at -e line 2
          main::g() called at -e line 2

Internally, this is implemented with $SIG{__WARN__} and $SIG{__DIE__} hooks.

Stack traces are also included if raw non-object references are thrown.

This module is compatible with all perl versions back to 5.6.2, without additional prerequisites. It contains workarounds for a number of bugs in the perl interpreter, some of which effect comparatively simpler modules, like Carp::Always.


import( @options )

Enables stack traces and sets options. A list of options to enable can be passed in. Prefixing the options with no_ will disable them.


Enable attaching stack traces to exception objects. Enabled by default.


Load the Devel::Confess::Builtin module to use built in stack traces on supported exception types. Disabled by default.


Dumps the contents of references in arguments in stack trace, instead of only showing their stringified version. Also causes exceptions that are non-object references and objects without string overloads to be dumped if being displayed. Shows up to three references deep. Disabled by default.

dump0, dump1, dump2, etc

The same as the dump option, but with a different max depth to dump. A depth of 0 is treated as infinite.


Colorizes error messages in red and warnings in yellow. Disabled by default.


Includes a snippet of the source for each level of the stack trace. Disabled by default.

source0, source1, source2, etc

Enables source display, but with a specified number of lines of context to show. Context of 0 will show the entire source of the files.


Similar to the source option, but only shows includes source for string evals. Useful for seeing the results of code generation. Disabled by default. Overrides the source option.

evalsource0, evalsource1, evalsource2, etc

Enables eval source display, but with a specified number of lines of context to show. Context of 0 will show the entire source of the evals.


Use more informative names to string evals and anonymous subs in stack traces. Enabled by default.


Add stack traces to errors. Enabled by default.


Add stack traces to warnings. Enabled by default.

The default options can be changed by setting the DEVEL_CONFESS_OPTIONS environment variable to a space separated list of options.



Classes or roles added to this hash will not have stack traces attached to them. This is useful for exception classes that provide their own stack traces, or classes that don't cope well with being re-blessed. If Devel::Confess::Builtin is loaded, it will automatically add its supported exception types to this hash.

Default Entries:


Provides a stack trace


Provides a stack trace


The idea and parts of the code and documentation are taken from Carp::Always.



This module uses several ugly tricks to do its work and surely has bugs.


Please report bugs via CPAN RT.




Copyright (c) 2005-2013 the "AUTHORS" and "CONTRIBUTORS" as listed above.


This library is free software and may be distributed under the same terms as perl itself. See

syntax highlighting: