CGI Setup and Troubleshooting

CGI, and Perl Troubleshooting

With any CGI program, there are several common elements that can be checked to determine why a CGI script is failing.  You may wish to print this list.  If you have any additional suggestions, please let us know.

1.  Did you upload the script(s) with minimal changes?
2.  Did you save the files with a true text editor (possibly with Unix save mode)?
3.  Did you upload the script(s) in ASCII mode?
4.  Did you set the correct permissions?  (chmod correct?)
5.  Did you store the CGI Script in cgi-bin?
6.  Is the first line in the script  #!/usr/bin/perl   ?
7.  Perl is case sensitive, are you calling everything correctly?
8.  Did you escape \ the @ in any email addresses?
9.  Are you using the correct server root path?
10.  Is your CGI Script located in the cgi-bin folder?
11.  Have you used SSH Telnet in order to discover error messages?
12. Is your sendmail path correct? 
13.  Be careful deleting server files that preexist on your web account.
14. Are you using SHTML and SSI correctly?
15. Are none of your images displaying?

CGI Script Setup

1.  Our number one suggestion with all cgi scripts is to first set them up without making any modifications except which is absolute necessary (like don't bother with changing the admin email, don't make any customizations to the HTML, etc.).  Then once it is running, after each change, re-upload and recheck the script for any possible problems.

Editing your CGI Scripts

2. DO: Make sure to only use a text editor program to edit your cgi programs.  You may wish to use Editeur located at as it can save Unix files (this is the program we use), feel free to search for more at or  Just make sure the text editor that you use can save as a Unix file.

DON'T: Use WordPad, Microsoft Word, or some other word processing program to edit your CGI scripts.  These programs may corrupt your CGI programs.  Most word processing programs have a "save as ASCII or TEXT" but even though the word processing program appears to save in ASCII or text format, it still may corrupt the CGI program.

DON'T: Use Microsoft FrontPage to  upload your CGI files.  However, it is possible, but if you wish to do so, you will have to customize your FrontPage setup files located on your computer for each web site in order to do so.   Again, we recommend against it.

FTP Considerations - ASCII & Auto Detect

3.  Make sure your FTP software uploads the CGI scripts in ASCII mode, binary mode will corrupt the CGI files.

Some FTP software may have an Auto detect mode.  The Auto Detect mode may not see .cfg, .dat, .database, .db, .pl, etc. as needing ASCII mode, but typically files such as this do need to be transferred in ASCII mode.  FTP software can be found here.

Permissions - chmod

4.  Make sure to double check all permissions (for both files and folders).  You can change permission by SSH Telnet or by using your FTP software (the recommending method).  Changing permissions is also referred to as chmod.

Location - cgi-bin

5.  Make sure that any CGI Script or PL script is stored inside the cgi-bin folder.  You can create additional folders inside the cgi-bin to maintain organization.

Perl Location

6.  Make sure the first line of the cgi program points to the location of Perl.

The location of Perl at is #!/usr/bin/perl

Unix/Linux Insight

7.  Unix/Linux is case sensitive.

Email and the @ Symbol

8.  In most cases an email address that resides in a CGI script must have the @ symbol escaped such as yourname\  Not escaping the @ symbol will cause the CGI program to fail to run.

Server Root Path

9.  Make sure you have checked your root path (if your CGI script needs this information) as inaccurate information will certainly cause a CGI script to fail.

The root path at is /home/your_ftp_name/public_html

For example, if your script is located at...
then the root path to web_store.cgi would be...

403 Forbidden

10.  Is your script located in the cgi-bin?   All scripts at must be located in the cgi-bin in order to run.

Help via SSH Telnet

11.  If your script continues to fail, you can also log in to your account via SSH Telnet.  Then locate your script and then run:

perl  yourscriptname.cgi

Based upon the error messages, edit the script and re-upload.


12.  If you are experiencing email problems with your CGI script, make sure you have set the correct path to sendmail in your cgi script.

The location of sendmail at is /usr/sbin/sendmail

To Delete or Not to Delete

13.  If you see files like .bash_logout, .screenrc, etc. don't delete them as they will affect your entire web account.  They are there for a reason.

Folders that begin with  _vti are related to Microsoft Front Page and should also be left alone.  Though they won't affect your CGI scripts whether you delete them or not.

Are You Using SHTML and SSI Correctly?

14.  If you call or run a CGI or PL program from an HTML document in a statement such as...

<!--#exec cgi="/cgi-bin/counter/counter.cgi"-->

...visit the SSI / SHTML page which may help you discover solutions and find answers to common questions regarding SSI and SHTML.

Are None of Your Images Displaying?

15.  If none of your images are displaying in your online program, it is due to one of the following reasons...

Have you FTP/Uploaded your images to the correct location on the server?  While running the program via your browser, view the HTML source code, and look at the full path of an image.  Is this where you stored your image?  If not, move your image(s) to the correct location.

Most Unix/Linux hosts (including don't allow images to display if they are located in the cgi-bin folder.  Typically your images must reside OUTSIDE the cgi-bin folder.  This is done because many online programs require setup files, store sensitive data, etc. inside the cgi-bin folder.  To minimize the risk of a visitor to your web site from intentionally or unintentionally displaying things they shouldn't see that is located in the cgi-bin folder, hosting companies typically only allow your visitors to run programs located in the cgi-bin, but are not allowed to view any other files (which includes images, text files, etc.).


Please note that scripts can enter infinite loops and cause problems for any server.  Please edit scripts with care!

For additional assistance visit our CGI-bin Applications Page.

[Manual Index]


Copyright 2000-2006 All Rights Reserved. Terms and Conditions of Use and Privacy Policy. - Your Success Is Our Success