|Previous||Table of Contents||Next|
What to Do When Your CGI Program Doesn't Work
The following sections provide a general-purpose CGI program debugging guide. Before you read through all this information to find the problem in your first CGI program, go back through the instructions to make sure you didn't skip any steps.
By the time you reach the end of this hour, you should be able to find any problems your CGI program has.
The diagnostics in these sections assume you're debugging a program named hello.cgi. If your program has another name, use it instead.
Is It Your CGI Program?
The first potential source of problems to eliminate is the CGI program itself. There's no sense in debugging web server configurations if the CGI program doesn't work.
CGI programs can be run interactively like all Perl programs, and running them this way is very useful for debugging. To run your program, start it from the command prompt like this:
The Perl interpreter should reply with a line that looks like this:
(offline mode: enter name=value pairs on standard input)
This prompt indicates that the CGI module is attempting to get your CGI form values; they are covered in Hour 22, "Basic Forms."
To this prompt, you should—for now—respond with just an end-of-file character. Under Unix, it is Ctrl+D; you just press the Ctrl key and type D. In Windows, you press Ctrl+Z. Perl should then print the following:
Content-Type: text/html <b>Hello, World!</b>
The Content-Type: text/html message indicates that what follows should be interpreted as text or HTML. The meaning of this message is covered fully in Hour 24. For now, just know that it's important that this message is the first thing printed by your program—with the header function—and that it's necessary. If anything else is emitted before the Content-Type message, the CGI program will fail.
Problem: Perl responds with a syntax error.
Solution: Fix the syntax error.
Problem: Perl responds with Can't locate CGI.pm in @INC....
Solution: Your Perl installation is incomplete. The CGI module ships with Perl by default. If you need to reinstall it, see Appendix A, "Installing Modules." Make sure you've spelled CGI correctly.
After you've eliminated your script as the cause of the problems, it's time to check the script's installation and the server's configuration.
Problem: The server responds with the message Not Found or 404 Not Found.
Solution: These messages usually indicate one of the following two problems:
Problem: The text of your script is displayed.
Solution: The program is displayed because the web server thinks that the program is really a document, not a program to be executed.
Problem: The server responds with the message Forbidden or 403 Error.
Solution: The permissions on the CGI program are not correct. This problem is most likely to occur on a Unix web server.
You can view the permissions on the hello.cgi program by typing ls -l hello.cgi at a command prompt in the proper directory. If you have FTP access to the server, you can view the file permissions by typing dir. The permissions should look something like this:
-rwxr-xr-x 1 user 93 Aug 03 23:06 hello.cgi
The permissions are the rwxr-xr-x characters on the left. If they don't look exactly like this, go back to the installation instructions for details on how to properly set the permissions on the CGI program.
Fixing Internal Server or 500 Errors
If the server replies with an Internal Server Error or 500 Error message, this means that your CGI program failed somehow. This general-purpose failure message is generated by many different problems.
The most important tool you have in debugging an "Internal Server Error" is the server's log file. As the web server receives requests for web pages, it writes each page request into a file for later analysis. Any errors that the server encounters are also logged, including error messages generated by CGI programs.
Find the location of the server error log file, which you should have noted in the checklist. The log is typically written by appending any new items to the bottom of the log file. To see the last few entries under Unix, at a command prompt, type
to see just the bottom of the file. Some web servers have a utility—often a CGI program itself—to view the log file. If you have FTP-only access to the server, you might need to download the log file and view it on your local PC to see the error entries.
If you do not have access to the server's error logs, you have a big problem. Finding an "Internal Server Error" will be a hit-and-miss affair. Following the checklist shown here, you should find the problem eventually. (The messages you'll find in the server logs are approximated; the text will vary from server to server.)
Log entry: No such file or directory: exec of /cgi-bin/hello.cgi failed
Log entry: Can't locate CGI.pm in @INC....
Possible causes: The Perl installation is incomplete, corrupt, or very old. Perl is apparently unable to locate the CGI module, which is a standard part of the Perl installation. You might need to reinstall the module or contact your system administrator to have him or her reinstall Perl. See Appendix A.
Log entry: Syntax error, warning, Global symbol requires, and so on
Possible causes: Your Perl program apparently has a typo or incorrect syntax. Follow the instructions in the "Is It Your CGI Program?" section to determine the problem.
Log entry: Premature end of script headers
Possible causes: This catchall error message describes any situation in which your script is run, and the Content-Type header—printed by the CGI module's header function—is not the first thing emitted by the script. Sometimes a secondary message appears in the log file, immediately before or after this one. The other message may be more helpful in determining what went wrong. You can try these solutions:
|Previous||Table of Contents||Next|