Common CGI Problems and How To Fix Them
If you've ever tried installing a CGI or Perl script on to your server, then you're probably familiar with the following situation: you've found a great script, followed the instructions, uploaded it to your server, and now quivering with gleeful anticipation you load up your web browser, point it to the right address and... bang, there isn't your script, instead you've got a cryptic error message such as "Error 403", "Error 500", "Internal Server Error" or something else completely unexpected.
Preventing Problems
First of all there are some guidelines that you should always follow when you are uploading or installing CGI scripts on a server. Follow these and your life will be much easier!
Before you upload
- Open the script in a text editor (such as Windows Notepad, but not MS Word or any other Word Processor), look at the first line of the script. It will probably look something like: #!/usr/bin/perl you may need to change this to match the path to your Perl interpreter (this should be supplied by your host).
- If the script comes with a file called readme, readme.txt, readme.1st or something similar then read it! This should contain instructions on how to install, configure and run the script and will tell you exactly what you need to do.
- If your host has any restrictions on which directories you can use (normally the \cgi-bin directory) or which file extensions can be used (normally either .cgi or .pl), then take note and make any appropriate changes.
When you upload:
- Use a proper FTP program to upload your script, such as LeechFTP or WS_FTP
- Set your FTP program to upload in Text or ASCII mode
- If you are using a Unix or Linux based server you will also need to set the file permissions (chmod) to allow your script to run, normally 755 but check the readme file.
It's not working. What do you do now?
The first, and simplest error message to cure is the old, familiar "Error 404". The standard web "file not found" error message. All this means is that the server can't find the file that you're looking for. This is most likely down to one of two reasons:
- You haven't uploaded the script to your server yet, or you have uploaded it but have accidentally saved it in a different place.
- You've typed the URL into your browser wrongly. Make sure you type in the full server name, path to the script and script name exactly the same as the server and path that you've uploaded it to, and that you've spelt the script name correctly and remembered to type the extension in (normally either .pl or .cgi).
Most other errors fall into two different categories, either because your host/server has placed certain restrictions on how CGI programs can be run or errors with the installation, configuration and execution of the script.
Restrictions imposed by your webhosting company or your webserver. Before attempting to install and run CGI programs you should check with your host to see that they allow CGI and check their specific conditions. If you are running your own server then you should check your documentation and ensure that you have all of the relevant software set up properly (as a minimum you will need to have both a web server and a version of Perl (version 5 as a minimum) installed and running on the machine that you are using as a server). Once you have the relevant details check the following:
- Does your host support/allow CGI or Perl programs to be run on the server? Check with your host to find out, most paid-for hosting will allow you to upgrade to CGI if you don't already have it, and there are some free hosts that will allow CGI.
- Does your host only allow certain pre-checked scripts to be installed on the server? Badly written CGI programs can potentially damage the server that they are running on, so some hosts will only allow you to use CGI scripts supplied by them, or certain well known scripts from sources trusted by them. If this is the case then you need to either upgrade to a full CGI package, or change to another host that allows you to install and run your own CGI scripts.
- Is your server set up so that CGI scripts will only work if they are in a certain directory (eg /cgi-bin/)?. Check with your host to see if they have any restrictions of this kind and make sure that you upload your scripts to the specified directory, or a subdirectory of that.
- Does your script have the right extension on it's filename? Many servers will only run Perl or CGI programs if their filename ends with either ".pl" or ".cgi", similarly they may only allow you to use SSI commands in files that end with ".shtml". Again check with your host to see if they have any restrictions of this kind set, and amend your filenames accordingly.
Other common error codes and what they mean
So you've followed all of the guidelines above and you're still getting errors, this is what they mean:
- "Error 403: Permission denied" This normally happens when you haven't set the file permissions properly so that the file can execute. Most scripts need to be set (CHMODed) to 755, your FTP software should let you set these properties.
- "Error 500: Configuration error" There are two main reasons for this error. Either you've set the path to Perl wrongly in the first line of your script (the bit that looks like #!/usr/bin/perl). Or you have uploaded the file with your FTP program set to binary mode, re-upload the file making sure that your FTP software is set to ASCII or Text mode.
- Most other error messages are caused by a problem within the script itself. Some hosts may give you access to the CGI error logs, some won't, if yours doesn't, then you're going to have to rely on the error messages that your server outputs to the web page. If you wrote the script yourself, then double check the syntax (watch out for missed semi-colons) and consider installing Perl on your own computer to make testing scripts easier.
This site is designed for and will work and look better in a browser that supports web standards (including CSS-2), but it is accessible to any browser or Internet device.
'No, Mr Bond, I expect you to die' - Auric Goldfinger to James Bond [Goldfinger]
