General Advice

Having the warnings turned on, immensly helps to detect possible problems. See The Importance of Warnings.

Enabling use diagnostics; generally helps you to determine the source of the problem and how to solve it. See diagnostics pragma for more info.

Building and Installation

See make Troubleshooting and make test Troubleshooting

Configuration and Startup

This section talks about errors reported when you attempt to start the server.

libexec/libperl.so: open failed: No such file or directory

If when you run the server you get the following error:

libexec/libperl.so: open failed: No such file or directory

The above error seems to indicate that perl was compiled with a shared library. mod_perl does detect this and links the apache executable to the perl shared library (libperl.so).

First of all make sure you have perl installed on the machine, and that you have libperl.so in <perlroot/<version>/<architecture>/CORE>. For example in /usr/local/lib/perl5/5.00503/sun4-solaris/CORE.

Then make sure that that directory is included in the environment variable LD_LIBRARY_PRELOAD. Under normal circumstances, apache should have the path configured at compile time, but this way you can override the library path.

Invalid command 'PerlHandler'...

Syntax error on line 393 of /etc/httpd/conf/httpd.conf: Invalid
command 'PerlHandler', perhaps mis-spelled or defined by a module
not included in the server configuration [FAILED]

Happens when you have a mod_perl enabled Apache compiled with DSO (Generally it's an installed RPM or other binary package). You have to tell apache to load mod_perl by adding:

AddModule mod_perl.c

in your config file.

RegistryLoader: Cannot translate the URI /home/httpd/perl/test.pl

(Meta: I've changed this warning message in the module - update it!!!)

RegistryLoader: Cannot translate the URI /home/httpd/perl/test.pl
            into a real path to the filename. Please refer to the
            manpage for more information
            or use the complete method's call like:
            $r->handler(uri,filename);\n";

This warning shows up when RegistryLoader fails to translate the URI into the corresponding filesystem path. Most of failures happen when one passes a file path instead of URI. (A reminder: /home/httpd/perl/test.pl is a file path, while /perl/test.pl is an URI). In most cases all you have to do is to pass something that RegistryLoader expects to get - the URI, but there are more complex cases. RegistryLoader's man page shows how to handle these cases as well (watch for the trans() sub).

"Apache.pm failed to load!"

If your server startup fails with:

Apache.pm failed to load!

error, try adding to httpd.conf:

PerlModule Apache

directive.

Code Parsing and Compilation

Value of $x will not stay shared at - line 5

my() Scoped Variable in Nested Subroutines.

Value of $x may be unavailable at - line 5.

my() Scoped Variable in Nested Subroutines.

Can't locate loadable object for module XXX

There is no object built for this module. e.g. when you see:

Can't locate loadable object for module Apache::Util in @INC...

make sure to give mod_perl's Makefile.PL PERL_UTIL_API=1, EVERYTHING=1 or DYNAMIC=1 parameters to enable and build all the components of Apache::Util.

Can't locate object method "get_handlers"...

Can't locate object method "get_handlers" via package "Apache"

You need to rebuild your mod_perl with stacked handlers, i.e. PERL_STACKED_HANDLERS=1 or more simply EVERYTHING=1.

Missing right bracket at line ...

Most chances you really have a syntax error. However the other reason might be a script running under Apache::Registry and using <__DATA__> or <__END__> tokens. Learn why

Can't load '.../auto/DBI/DBI.so' for module DBI

Check that all your modules are compiled with the same perl that is being compiled into mod_perl. perl 5.005 and 5.004 are not binary compatible by default.

Other known causes of this problem:

OS distributions that ship with a (broken) binary Perl installation.

The `perl' program and `libperl.a' library are somehow built with different binary compatibility flags.

The solution to these problems is to rebuild Perl and any extension modules from a fresh source tree. Tip for running Perl's Configure script: use the `-des' flags to accepts defaults and `-D' flag to override certain attributes:

% ./Configure -des -Dcc=gcc ... && make test && make install

Read Perl's INSTALL doc for more details.

Solaris OS specific:

Can't load DBI or similar Error for the IO module or whatever dynamic module mod_perl tries to pull in first. The solution is to re-configure, re-build and re-install Perl and dynamic modules with the following flags when Configure asks for "additional LD flags":

-Xlinker --export-dynamic

or

-Xlinker -E

This problem is only known to be caused by installing gnu ld under Solaris.

Runtime

Incorrect line number reporting in error/warn log messages

See Use of uninitialized value at (eval 80) line 12.

rwrite returned -1

That message happens when the client breaks the connection while your script is trying to write to the client. With Apache 1.3.x, you should only see the rwrite messages if LogLevel is set to debug.

There was a bug that reported this debug message regardless the value of LogLevel directive. It has been fixed in mod_perl 1.19_01 (CVS version).

Generally a LogLevel is either debug or info. debug logs everything, info is the next level, which doesn't include debug messages. You shouldn't use a "debug" mode on your production server. And as of this moment there is no way to stop users from aborting connections.

caught SIGPIPE in process

[modperl] caught SIGPIPE in process 1234
[modperl] process 1234 going to Apache::exit with status...

That's the $SIG{PIPE} handler installed by mod_perl/Apache::SIG, called if a connection timesout or Client presses the 'Stop' button. It gives you an opportunity to do cleanups if the script was aborted in the middle of its execution. See Handling the 'User pressed Stop button' case for more info.

If your mod_perl version < 1.17 you might get the message in the following section...

Client hit STOP or Netscape bit it!

Client hit STOP or Netscape bit it!
Process 2493 going to Apache::exit with status=-2

You will see this message in mod_perl < 1.17. See caught SIGPIPE in process.

Global symbol "$foo" requires explicit package name

The script below will print a warning like above, moreover it will print the whole script as a part of the warning message:

#!/usr/bin/perl -w
use strict;
print "Content-type: text/html\n\n";
print "Hello $undefined";

The warning:

Global symbol "$undefined" requires explicit package name at /usr/apps/foo/cgi/tmp.pl line 4.
        eval 'package Apache::ROOT::perl::tmp_2epl;use Apache qw(exit);sub handler {
#line 1 /usr/apps/foo/cgi/tmp.pl
BEGIN {$^W = 1;}#!/usr/bin/perl -w
use strict;
print "Content-type: text/html\\n\\n";
print "Hello $undefined";


}
;' called at /usr/apps/lib/perl5/site_perl/5.005/aix/Apache/Registry.pm line 168
        Apache::Registry::compile('package
	Apache::ROOT::perl::tmp_2epl;use Apache qw(exit);sub han...') 
	called at /usr/apps/lib/perl5/site_perl/5.005/aix/Apache/Registry.pm line 121
        Apache::Registry::handler('Apache=SCALAR(0x205026c0)') called at /usr/apps/foo/cgi/tmp.pl line 4
        eval {...} called at /usr/apps/foo/cgi/tmp.pl line 4
[Sun Nov 15 15:15:30 1998] [error] Undefined subroutine &Apache::ROOT::perl::tmp_2epl::handler called at /
usr/apps/lib/perl5/site_perl/5.005/aix/Apache/Registry.pm line 135.

[Sun Nov 15 15:15:30 1998] [error] Goto undefined subroutine &Apache::Constants::SERVER_ERROR at /usr/apps
/lib/perl5/site_perl/5.005/aix/Apache/Constants.pm line 23.

The error is simple to fix. When you use the use strict; pragma (and you should...), all variables should be defined before being used.

The bad thing is that sometimes the whole script (possibly, thousands of lines) is printed to error_log file as a code that the server has tried to eval()uate.

As Doug answered to this question:

Looks like you have a $SIG{__DIE__} handler installed (Carp::confess?).
That's what's expected if so.

It wasn't in my case, but may be yours.

Bryan Miller said:

You might wish to try something more terse such as 
"local $SIG{__WARN__} = \&Carp::cluck;"  The confess method is _very_
verbose and will tell you more than you might wish to know including
full source.

Use of uninitialized value at (eval 80) line 12.

Your code includes some undefined variable that you have used as if it was already defined and initialized. For example:

$param = $q->param('test');
print $param;

vs.

$param = $q->param('test') || '';
print $param;

In the second case, $param will always be defined, either $q->param('test') returns some value or undef.

Also read about finding the Line Number the Error/Warning has been Triggered at.

Undefined subroutine &Apache::ROOT::perl::test_2epl::some_function called at

See Names collisions with Modules and libs.

Callback called exit

Callback called exit is just a generic message when some unrecoverable error occurs inside Perl during perl_call_sv() (which mod_perl uses to invoke all handler subroutines. Such problems seem far less with 5.005_03 than 5.004.

Sometimes you discover that your server is not responding and its error_log has filled up the remaining space on the file system. When you get to see the contents of the error_log -- it includes millions of lines, like:

Callback called exit at -e line 33, <HTML> chunk 1.

Why the looping?

Perl can get *very* confused inside an endless loop in your code, it doesn't mean your code called exit(), but Perl's malloc went haywire and called croak(), but no memory is left to properly report the error, so Perl is stuck in a loop writing that same message to stderr.

Perl 5.005+ plus is recommended for its improved malloc.c and other features that improve mod_perl and come turned on by default.

See also "Out_of_memory!"

Out of memory!

If something goes really wrong with your code, Perl may die with an "Out of memory!" message and/or "Callback called exit". Common causes of this are never-ending loops, deep recursion, or calling an undefined subroutine. Here's one way to catch the problem: See Perl's INSTALL document for this item:

=item -DPERL_EMERGENCY_SBRK

If PERL_EMERGENCY_SBRK is defined, running out of memory need not be a
fatal error: a memory pool can allocated by assigning to the special
variable $^M.  See perlvar(1) for more details.

If you compile with that option and add 'use Apache::Debug level => 4;' to your PerlScript, it will allocate the $^M emergency pool and the $SIG{__DIE__} handler will call Carp::confess, giving you a stack trace which should reveal where the problem is. See the Apache::Resource module for prevention of spinning httpds.

Note that perl-5.005+ has PERL_EMERGENCY_SBRK turned on by default.

The other trick is to have a startup script initialize Carp::confess, like so:

use Carp ();
eval { Carp::confess("init") };

this way, when the real problem happens, Carp::confess doesn't eat memory in the emergency pool ($^M).

server reached MaxClients setting, consider raising the MaxClients setting

See Choosing MaxClients.

syntax error at /dev/null line 1, near "line arguments:"

syntax error at /dev/null line 1, near "line arguments:"
Execution of /dev/null aborted due to compilation errors.
parse: Undefined error: 0

There is a chance that your /dev/null device is broken. Try:

% sudo echo > /dev/null

Can't call method "register_cleanup" (CGI.pm)

Can't call method "register_cleanup" on an
undefined value at /usr/lib/perl5/5.00503/CGI.pm line 263.

caused by this code snippet in CGI.pm:

if ($MOD_PERL) {
  Apache->request->register_cleanup(\&CGI::_reset_globals);
  undef $NPH;
}

The solution is to add to httpd.conf:

PerlPostReadRequestHandler 'sub { Apache->request(shift) }'

But even better swicth to Apache::Cookie:

use Apache;
use Apache::Cookie;

sub handler {
  my $r = shift;
  my $cookies = Apache::Cookie->new($r)->parse;
  my %bar = $cookies->{foo}->value;
}

Shutdown and Restart

Evil things might happen when using PerlFreshRestart

Unfortunately, not all perl modules are robust enough to survive reload, for them, unusual situation. PerlFreshRestart does not much more than:

while (my($k,$v) = each %INC) {
  delete $INC{$k};
  require $k;
}

Besides that, it flushes the Apache::Registry cache, and empties any dynamic stacked handlers (e.g. PerlChildInitHandler).

Lots of SegFaults and other problems were reported by users who have turned PerlFreshRestart On. Most of them have gone away when it was turned off. It doesn't mean that you shouldn't use it, if it works for you. Just be aware of the dragons...

Constant subroutine XXX redefined

That's a mandatory warning inside Perl. It happens only if you modify your script and Apache::Registry reloads it. Perl is warning you that the subroutine(s) were redefined. It is mostly harmless. If you don't like seeing those, just kill -USR2 (graceful restart) apache when you modify your scripts.

You aren't supposed to see these warnings when you don't modify the code with perl 5.004_05 or 5.005+.and higher. If you still experince a problem with code within a CGI script, moving all the code into a module (or a library) and requiring it should solve the problem.

Can't undef active subroutine

Can't undef active subroutine at
/usr/apps/lib/perl5/site_perl/5.005/aix/Apache/Registry.pm line 102.
Called from package Apache::Registry, filename
/usr/apps/lib/perl5/site_perl/5.005/aix/Apache/Registry.pm, line 102

This problem is caused when, a client drops the connection while httpd is in the middle of a write, httpd timeout happens, sending a SIGPIPE, and Perl in that child is stuck in the middle of its eval context. This is fixed by the Apache::SIG module which is called by default. This should not happen unless you have code that is messing with $SIG{PIPE}. It's also triggered only when you've changed your script on disk and mod_perl is trying to reload it.

[warn] child process 30388 did not exit, sending another SIGHUP

From mod_perl.pod: With Apache versions 1.3.0 and higher, mod_perl will call the perl_destruct() Perl API function during the child exit phase. This will cause proper execution of END blocks found during server startup along with invoking the DESTROY method on global objects who are still alive. It is possible that this operation may take a long time to finish, causing problems during a restart. If your code does not contain and END blocks or DESTROY methods which need to be run during child server shutdown, this destruction can be avoided by setting the PERL_DESTRUCT_LEVEL environment variable to -1.

Windows OS specific notes

Apache::DBI

Apache::DBI causes the server to exit when it starts up, with:

[Mon Oct 25 15:06:11 1999] file .\main\http_main.c, line 5890,
assertion "start_mutex" failed

Build mod_perl with PERL_STARTUP_DONE_CHECK set (e.g. insert

#define PERL_STARTUP_DONE_CHECK 1

at the top of mod_perl.h or add it to the defines in MSVC++ Options dialog).

Apache loads all Apache modules twice, to make sure the server will successfully restart when asked to. This flag disables all PerlRequire and PerlModule statements on the first load, so they can succeed on the second load. Without that flag, the second load fails.

cpanm mod_perl_guide

perl -MCPAN -e shell
install mod_perl_guide