Perl Scripts ·
Perl CGI.pm Basics: Parameters, Redirects and Errors
By Manu Mathew, Technical Lead Engineer · Published 5 November 2014 · Last updated 5 October 2026

Many older Perl web applications still run on CGI.pm, and the same few questions come up whenever one needs a fix: how to read the form, how to redirect, and where the errors went. This note answers them with tested examples. It also replaces three older, shorter notes on this site, on redirects, new CGI and error logs.
Quick answer
Call $q->param with no arguments to get all parameter names. For a single value, use scalar $q->param('name'). For fields that can send several values, such as checkboxes, use $q->multi_param('name'). Avoid calling param('name') in list context, for example inside a hash or a function call. For file upload fields, see Perl CGI.pm file uploads.
How do I read all the parameters?
use strict;
use warnings;
use CGI;
my $q = CGI->new;
my @names = $q->param; # all names, in the order they arrived
my $name = scalar $q->param('name'); # one value
my @colours = $q->multi_param('colour'); # several values for one name
for my $param ($q->param) {
my @values = $q->multi_param($param);
print "$param => [@values]\n";
}
With the query string name=Asha&colour=red&colour=blue¬e=, @names is name colour note and @colours is red blue.
What is the difference between an empty and a missing parameter?
A parameter that was sent but left empty (note=) returns an empty string. A parameter that wasn’t sent at all returns undef. Test with defined when the difference matters.
Why is param() in list context risky?
In list context, param('name') returns every value sent for that name. Someone can send extra values on purpose to add keys to a hash:
# Request: ?name=Asha&name=role&name=admin
my %user = (role => 'user', name => $q->param('name')); # list context
print "role: $user{role}\n"; # admin
my %safe = (role => 'user', name => scalar $q->param('name'));
print "role: $safe{role}\n"; # user
CGI.pm warns about this (“CGI::param called in list context … this can lead to vulnerabilities”). Using scalar or multi_param makes your intent explicit and silences the warning. Setting $CGI::LIST_CONTEXT_WARN = 0 only hides the warning, so fix the call instead.
How do I redirect to another page with CGI.pm?
Print $q->redirect($url) instead of $q->header, and print nothing before it.
use strict;
use warnings;
use CGI;
my $q = CGI->new;
print $q->redirect(-uri => 'https://www.example.com/thank-you/', -status => '303 See Other');
The output is just the headers (Status: 303 See Other and a Location line). A 303 suits the page after a form post, because the browser follows it with a normal GET, so refreshing the thank-you page doesn’t send the form again. Use a full URL, and if the target comes from a parameter, check it against a list of your own pages so the script can’t be used to send visitors to someone else’s site.
Should I write new CGI or CGI->new?
Write CGI->new. The older new CGI form (indirect object syntax) only works because Perl guesses that new is a method, and that guess can go wrong.
In Perl, new is an ordinary method name, not a keyword. If a subroutine called new exists in the current package, or the class name could be read as something else, new CGI can call the wrong thing. CGI->new has only one meaning. Since Perl 5.36, use v5.36 turns the indirect syntax off, so code written the old way stops compiling.
How do I send Perl CGI errors to the error log?
use CGI::Carp; adds a timestamp and the script name to every warn and die message in the web server’s error log, and carpout can send them to a file of your own.
use strict;
use warnings;
use CGI;
use CGI::Carp qw(carpout);
open my $log, '>>', '/var/log/myapp/errors.log' or die "Cannot open log: $!";
carpout($log); # warn and die messages now go to this file
my $q = CGI->new;
warn "Something looked odd\n"; # [Sun Oct 4 22:38:08 2026] script.pl: Something looked odd
print $q->header('text/plain'), "OK\n";
An older note here suggested fatalsToBrowser, which shows the full error in the visitor’s browser. That helps while you develop, but on a live site it can reveal file paths and database details, so leave it off in production and read the log instead.
Need help? If your Perl form handling is part of an older application that needs fixing or updating, I can take a look. See Perl development, or email manu@manu.co.in.
Frequently asked questions
Is CGI.pm still maintained?
Yes. CGI.pm still gets releases on CPAN, but it left the Perl core in Perl 5.22, so install it separately. Its documentation points new projects towards modern frameworks; for keeping an existing CGI application running, it remains a reasonable choice.
How do I read JSON sent to a CGI script?
For a POST with the type application/json, CGI.pm leaves the body unparsed in $q->param('POSTDATA'). Decode it with JSON::PP, a core module: decode_json(scalar $q->param('POSTDATA')). Check the content type first, and wrap the decode in eval to handle invalid JSON.
Should I escape parameters before printing them in HTML?
Yes. Pass every value from the visitor through escapeHTML, from CGI.pm or HTML::Entities, before it goes into a page, so a value containing a script tag shows as text instead of running. Use placeholders in database queries for the same reason.
How do I set a cookie with CGI.pm?
Create it with $q->cookie(-name => 'pref', -value => 'dark', -secure => 1, -httponly => 1) and pass it to the header: print $q->header(-cookie => $cookie);. On the next request, read it back with $q->cookie('pref').
Related notes: Perl CGI.pm file uploads; Perl DBI transactions; Perl files, folders, CSV and downloads; hiring a remote Perl developer.
Need help with Perl code?
If you have Perl code that needs fixing, extending or upgrading, I’m happy to take a look. I work remotely from Kozhikode, Kerala, with teams across India and elsewhere; Perl development and maintenance explains how I help. If you are deciding how to bring someone in, Hiring a remote Perl developer is a short checklist.
You can reach me through the contact section or email me at manu@manu.co.in. A few lines about the system and what you need is a good start.
An earlier version of this note reproduced sections of the CGI.pm documentation. This version is rewritten in my own words, with new examples.
Sources: CGI.pm documentation: Fetching the value or values of a single named parameter.