Authoring/Development - Debugging Perl Scripts

This tutorial is meant as a general outline for easing the strain of debugging Perl CGI scripts. It is more concerned with syntax errors than logical ones. A familiarity with SSH is assumed, although you can use most of the techniques locally on your code, if you have Perl installed on your own machine (there are versions for most operating systems).

"403 Forbidden Errors"

A 403 Forbidden error occurs when the Web server finds itself with insufficient permissions to run your script. Generally speaking, there are two steps to be taken when it occurs:

1. First, make sure you have given the script execute permissions. Via SSH, this is accomplished with:

   chmod 755 scriptname.cgi

   (See our File Permissions tutorial if you are not familiar with chmod.)

   If you are uploading via FTP, your FTP client probably has some facility for setting file permissions. You want to make sure that all choices (user, group, and other) have execute permission.

2. If your script does not have a .cgi or .pl extensions, it must be placed in the cgi-bin directory to be considered executable. If your script does not have one of these extensions, either rename it, move it into the cgi-bin directory, or add the following to .htaccess:

   AddHandler cgi-script .your_extension_here

"500 Internal Server Error"

The "500 Internal Server" error is likely to be the most common error message you will see while debugging your scripts. Unfortunately, it is also a very generalized error message, which reveals little other than that there is some problem with the script. To locate the problem or problems, a systematic approach is needed.

First and foremost, you should take care to always do the following:

1. If you are uploading the script to your server via SFTP/FTP, always make sure you have done so in ASCII format. If your SFTP/FTP client autodetects, make sure it knows that .cgi and .pl files are ASCII files. Uploading in BINARY format will cause problems.
2. Make sure the first line of your script is the path to Perl, and that it is correct. In the vast majority of cases, it should look like:

   #!/usr/local/bin/perl

   That is the path to Perl.

The next few techniques are all accomplished via SSH. We highly recommend the use of SSH while debugging scripts as it makes it much easier to make small changes to the script along with offering the ability to run the script from the command line.

First, use Perl's -c option from the command line to see if there are any syntax errors in the file, like this:

perl -c scriptname.cgi

Of course, replace "scriptname.cgi" with the actual filename. This command is the fastest way to find where the errors are in your file and fix them. If you find errors, keep correcting them and rerunning "perl -c" until they are gone. That's usually easier said than done, but generally Perl reports the line number with the error to you. An annoying exception occurs when you omit a left or right bracket. In such cases, the interpreter can get much farther in the script before the error occurs, reporting a certain line number when the missing bracket might actually be much earlier in the script.

Next, run the file and examine its first two lines of output. This might be done with:

perl scriptname.cgi | head -2 

The first line should be a content-type, most likely one of these:

Content-type: text/html
Content-type: text/plain

The second line, unless you are sending other headers like "Expires" or setting cookies, must be a blank line.

Every CGI script must first output its headers (starting with Content-type) followed by a blank line, or a 500 error will result. Please note that this technique will not always work if the script expects form input. You can also use "perldoc CGI" to read about using the CGI module for more advanced command-line debugging in that case.

The CGI::Carp module can be used to redirect error messages to your browser window for debugging purposes. Note that you should only use this while you are actively debugging, so that end users do not see any error messages. Add this to your Perl script:

use CGI::Carp qw(fatalsToBrowser warningsToBrowser);

All warnings and fatal errors will now be redirected to the browser.

Conclusion

By practicing all of these techniques, debugging Perl CGI scripts can be made a little easier and less frustrating as well.