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:


perl hello.cgi

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.

Server Problems

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:

The URL you used is incorrect. You typed http://www.server.com/cgi/hello.cgi when you should have typed http://www.server.com/cgi-bin/hello.cgi. Go back to the checklist and verify that the URL of your CGI directory is correct, you've spelled the name of the script right, and you have the right extension.
You placed the script in the wrong directory on the web server. Verify from the checklist that the CGI directory is correct, and if not, move the script to the correct location.

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.

You used the wrong extension on your CGI program. Instead of .pl, you used .cgi or some other wrong extension. Check the checklist, and make sure you're using the correct extension on your CGI program.
You put the script in the wrong directory, and you're using the wrong URL to access it. Verify that you've put the script in the correct CGI program directory and that you're using the right URL.
The server is misconfigured. If you're using your own web server, reread the documentation and verify that you've set it up correctly. Sometimes the installation includes a test CGI script; if so, try it. If you're using a commercial web hosting server, verify that you're placing your script in the correct directory, or contact the web host for help.

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


tail error_log

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

Possible causes:

The #! line of the script may not be correct. Make sure that the location of Perl in the #! line matches the location of Perl on the web server from the checklist. Verify that Perl is actually installed there by using ls or dir in FTP or locally.
If you used FTP to transfer the CGI program to the server, you may not have used ASCII mode for the transfer. Moving a script written in Windows to a Unix server—and vice versa—in binary mode does not work.
The permissions are not correct on the CGI program (Unix). See the description of Forbidden in the "Server Problems" section.

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:

Make sure you're not printing anything—including error messages—before calling the header function. Anything printed before the header function causes this error.
By the Way

You may see Perl CGI programs printing "Content-Type: text/html\n\n" at the beginning of the program instead of calling header. Apparently, printing this and calling header are supposed to do the same thing, but they don't. The header function takes into account that \n\n doesn't always mean the same thing on every server and emits the proper sequence for that server.
A problem called output buffering can cause output generated by the system function or backticks (``) to appear in the output before the header function's output. To make sure that the output from header is always shown first, you might want to try rewriting the beginning of your Perl CGI program to look like this:
```
#!/usr/bin/perl -wT

use strict;

use CGI;



$|=1;       # ensures that header's output always prints first

print header;
```

What to Do When Your CGI Program Doesn't Work