This resource is intended as a general framework for working through
problems with CGI scripts. It is not a complete guide to every
problem that you may encounter, nor a tutorial on bug squashing. It
is just the culmination of my experience debugging CGI scripts for ten
years. This page seems to have had many different homes, and I seem
to forget it exists, so I'm adding it to the Monastery's canon. You
can send any comments or suggestions to me at firstname.lastname@example.org. You may also
want to see the CGI
Meta FAQ for a list of references.
- Are you using Perl's built in features to help you find problems?
- If you have not turned on warnings with the -w switch and are not using
strict, you should be. These things help you find problems. You may need
a bit of time to get used to them, but they save you many hours of time.
You need them to go through this troubleshooting procedure.
- Did you output a valid CGI header first?
- The server is expecting the first output from a CGI
script to be the CGI header. Typically that might be as
simple as print "Content-type: text/plain\n\n";
or with CGI.pm and its derivatives,
. Some servers are sensitive to error output
(on STDERR) showing up before standard output (on STDOUT).
- What did the error log say?
- Servers keep error logs (or they should, at least).
Error output from the server and from your script should
show up there. Find the error log and see what it says.
There isn't a standard place for log files. Look in the
server configuration for their location, or ask the server
admin. You can also use tools such as CGI::Carp
to keep your own log files.
- What are the scripts permissions?
- If you see errors like "Permission denied" or "Method not
implemented", it probably means that your script is not
readable and executable by the web server user. On flavors
of Unix, changing the mode to 755 is recommended:
chmod 755 filename. Never set a mode to 777!
- Are you using use strict?
- Remember that Perl automatically creates variables when
you first use them. This is a feature, but sometimes can
cause bugs if you mistype a variable name. The pragma
use strict will help you find those sorts of
errors. It's annoying until you get used to it, but your
programming will improve significantly after awhile and
you will be free to make different mistakes.
- Does the script compile?
- You can check for compilation errors by using the -c
switch. Concentrate on the first errors reported. Rinse,
repeat. If you are getting really strange errors, check to
ensure that your script has the right line endings. If you
FTP in binary mode, checkout from CVS, or something else that
does not handle line end translation, the web server may see
your script as one big line. Transfer Perl scripts in ASCII
- Does the script give you warnings?
- You can check for warnings by using the -w switch which
I recommend you use during all development. Warnings are
fully explained in the perldiag man page, or by using the
pragma use diagnostics;. If you make your
script "-w clean" you will have less trouble with
it in the future.
- Is the script complaining about insecure dependencies?
- If your script complains about insecure dependencies, you
are probably using the -T switch to turn on taint mode, which is
a good thing since it keeps you have passing unchecked data to the shell. If
it is complaining it is doing its job to help us write more secure scripts. Any
data originating from outside of the program (i.e. the environment)
is considered tainted. Environment variables such as PATH and LD_LIBRARY_PATH
are particularly troublesome. You have to set these to a safe value
or unset them completely, as I recommend. You should be using absolute
paths anyway. If taint checking complains about something else,
make sure that you have untainted the data. See the perlsec
man page for details.
- What happens when you run it from the command line?
- Does the script output what you expect when run from the
command line? Is the header output first, followed by a
blank line? Remember that STDERR may be merged with STDOUT
if you are on a terminal (e.g. an interactive session), and
due to buffering may show up in a jumbled order. Turn on
Perl's autoflush feature by setting $| to a
true value. Typically you might see $|++; in
CGI programs. Once set, every print and write will
immediately go to the output rather than being buffered.
You have to set this for each filehandle. Use select to
change the default filehandle, like so:
Either way, the first thing output should be the CGI header
followed by a blank line.
$|++; #sets $| for STDOUT
$old_handle = select( STDERR ); #change to STDERR
$|++; #sets $| for STDERR
select( $old_handle ); #change back to STDOUT
- What happens when you run it from the command line with a CGI-like environment?
- The web server environment is usually a lot more limited
than your command line environment, and has extra
information about the request. If your script runs fine
from the command line, you might try simulating a web server
environment. If the problem appears, you have an
Unset or remove these variables
- all ORACLE_* variables
Set these variables
Recent versions of CGI.pm ( > 2.75 ) require the -debug flag to
get the old (useful) behavior, so you might have to add it to
your CGI.pm imports.
- REQUEST_METHOD (set to GET, HEAD, or POST as appropriate)
- SERVER_PORT (set to 80, usually)
- REMOTE_USER (if you are doing protected access stuff)
use CGI qw(-debug)
- Are you using die() or warn()?
- Those functions print to STDERR unless you have redefined
them. They don't output a CGI header, either. You can get
the same functionality with packages such as CGI::Carp.
- What happens after you clear the browser cache?
- If you think your script is doing the right thing, and
when you perform the request manually you get the right
output, the browser might be the culprit. Clear the cache
and set the cache size to zero while testing. Remember that
some browsers are really stupid and won't actually reload
new content even though you tell it to do so. This is
especially prevalent in cases where the URL path is the
same, but the content changes (e.g. dynamic images).
- Is the script where you think it is?
- The file system path to a script is not necessarily
directly related to the URL path to the script. Make sure
you have the right directory, even if you have to write a
short test script to test this. Furthermore, are you sure
that you are modifying the correct file? If you don't see
any effect with your changes, you might be modifying a
different file, or uploading a file to the wrong place.
(This is, by the way, my most frequent cause of such trouble
- Are you using CGI.pm, or a derivative of it?
- If your problem is related to parsing the CGI input and you
aren't using a widely tested module like CGI.pm, CGI::Request, or
CGI::Lite, use the module and get on with life. CGI.pm has a
cgi-lib.pl compatibility mode which can help you solve input
problems due to older CGI parser implementations.
- Did you use absolute paths?
- If you are running external commands with
system(), back ticks, or other IPC facilities,
you should use an absolute path to the external program.
Not only do you know exactly what you are running, but you
avoid some security problems as well. If you are opening
files for either reading or writing, use an absolute path.
The CGI script may have a different idea about the current
directory than you do. Alternatively, you can do an
explicit chdir() to put you in the right place.
- Did you check your return values?
- Most Perl functions will tell you if they worked or not
and will set $! on failure. Did you check the
return value and examine $! for error messages? Did you check
$@ if you were using eval?
- Which version of Perl are you using?
- The latest stable version of Perl is 5.8.3. Are you using an older
version? Different versions of Perl may have different ideas of warnings.
- Which web server are you using?
- Different servers may act differently in the same
situation. The same server product may act differently with
different configurations. Include as much of this
information as you can in any request for help.
- Did you check the server documentation?
- Serious CGI programmers should know as much about the
server as possible - including not only the server features
and behavior, but also the local configuration. The
documentation for your server might not be available to you
if you are using a commercial product. Otherwise, the
documentation should be on your server. If it isn't, look
for it on the web. Consult the CGI
Meta FAQ for a list of references.
- Did you search the archives of comp.infosystems.www.authoring.cgi?
- It's likely that someone has had your problem before,
and that someone (possibly me) has answered it in this
newsgroup. Archives are available from Google
- Can you reproduce the problem with a short test script?
- In large systems, it may be difficult to track down a bug
since so many things are happening. Try to reproduce the problem
behavior with the shortest possible script. Knowing the problem
is most of the fix. This may be certainly time-consuming, but you
haven't found the problem yet and you're running out of options. :)
- Did you decide to go see a movie?
- Seriously. Sometimes we can get so wrapped up in the problem that we
develop "perceptual narrowing" (tunnel vision). Taking a break,
getting a cup of coffee, or blasting some bad guys in Quake might give you
the fresh perspective that you need to re-approach the problem.
- Have you vocalized the problem?
- Seriously again. Sometimes explaining the problem aloud
leads us to our own answers. Talk to the penguin (plush toy) because
your co-workers aren't listening. If you are interested in this
as a serious debugging tool (and I do recommend it if you haven't
found the problem by now), you might also like to read The Psychology
of Computer Programming.
- Did you post an informative and well-developed question to comp.infosystems.www.authoring.cgi?
- Once you have gone through all of these steps, you
should have all of the information to ask a question that
can elicit a good answer. Post in as much detail as
possible, and include the smallest bit of code that
reproduces the problem.
brian d foy <email@example.com>
Edited by davido: Fixed HTML and formatting to eliminate horizontal scrolling in IE.
Are you posting in the right place? Check out Where do I post X? to know for sure.
Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
<code> <a> <b> <big>
<blockquote> <br /> <dd>
<dl> <dt> <em> <font>
<h1> <h2> <h3> <h4>
<h5> <h6> <hr /> <i>
<li> <nbsp> <ol> <p>
<small> <strike> <strong>
<sub> <sup> <table>
<td> <th> <tr> <tt>
Snippets of code should be wrapped in
<code> tags not
<pre> tags. In fact, <pre>
tags should generally be avoided. If they must
be used, extreme care should be
taken to ensure that their contents do not
have long lines (<70 chars), in order to prevent
horizontal scrolling (and possible janitor
Want more info? How to link or
or How to display code and escape characters
are good places to start.