Troubleshooting FastCGI


The following articles describe common errors and troubleshooting steps for FastCGI scripts.


FCGI is a protocol for allowing programs to interact with a web server. It improves performance over CGI by using persistent processes to handle a series of requests. Each FastCGI process can handle many requests over its lifetime. It avoids the overhead of per-request process creation and termination and allows a server to handle more web page requests simultaneously.

Configuration details

On DreamHost servers, FastCGI is handled by mod_fcgid. This Apache module provides a FastCGI interface specifically tuned for the dynamic FastCGI configuration used on DreamHost servers.


PHP is run through FastCGI by default at DreamHost.

Using $ENV{'QUERY_STRING'} instead of @ARGV

You cannot get the query string in FastCGI by using the @ARGV array. You must use $ENV{'QUERY_STRING'} instead. For example, add the following code to a file named


print "Content-type:text/html\n\n";

Next, visit the following URL.


You will see the value 123 is printed on the page.

Errors and troubleshooting


If an error occurs in your FastCGI script, it may not be returned immediately. If the script loads a web page, the page will appear to hang. When the script times out, it's possible that the error message may not be logged, and you'll only see a 500 error.


For the reasons stated above, testing under FastCGI is impractical. Development should be done on your local computer. FastCGI should only be added after the script has already been debugged.

Command line testing

Testing a script from the command line allows you to confirm if it will fail immediately.

This may not catch 100% of errors due to differences with %ENV.

For example:

[server]$ perl ~/

You can also add the -d flag for more debugging information.

[server]$ perl -d ~/

Killing an old process

Fixing an error may not fix the script immediately because the server could still be running an old version of the script from memory. To force the server to run the current version of the script, locate the old process name, then kill the process:

Make sure to change username to your Shell user.

[server]$ killall -u username processname

If the command above does not work, replace killall with killall -9.

Check the error.log file

Always check your site's error log file if you receive an error.

Check file and directory permissions

Make sure that the script you are trying to execute is set as executable.

[server]$ chmod +x myscript.fcgi

The directory the script is in and any directories above must also be writable.

[server]$ chmod -R 755 ~/

.htaccess file directives

Check your .htaccess file to see if there's a line referencing .cgi.

RewriteRule ^(.*)$ scriptname.cgi [QSA,L]

If so, update it to .fcgi.

RewriteRule ^(.*)$ scriptname.fcgi [QSA,L]

Clear your tmp directory

Finally, try deleting all sessions in your /tmp folder.

This option is only possible if your site is on a VPS or Dedicated Server.

See also

Did this article answer your questions?

Article last updated PST.

Still not finding what you're looking for?