Perch support

HomePerch 1 Tips and TroubleshootingPrinter Friendly Version

Perch 1 Tips and Troubleshooting

A collection of tips and troubleshooting advice that doesn't fit neatly into the other chapters. Check here if you are having problems as much of the content has been gathered after dealing with support requests.

1. Setup and Installation

1.1. When I go to the setup page my browser tries to download a file

If your browser tries to download a file rather than displaying the setup screen when you visit perch/setup the most likely problem is that your server is not running PHP or PHP is not configured properly.

If you should have PHP running then contact your hosting company for support. The Perch compatibility test suite should indicate any problems with PHP. If the test script runs correctly but you still have a problem with the setup page please open a ticket here and we will help you to get started.

1.2. I can see the Perch tags in my content when I view source

If you can see Perch tags in your content this means PHP is not running on your site or on the page that you are looking at. Please follow the following steps to work out what is happening.

  1. Have you run the Perch compatibility test suite and received a pass? This demonstrates that PHP is running on your server.
  2. Does the page that contains the tags have a .php extension?
  3. If the page is .htm or .html have you created a .htaccess file to run PHP on these pages as explained in the documentation

1.3. I have added Perch to my page and now get a blank page in the browser

If after adding the Perch runtime and/or a content tag you have either a completely empty page OR if you view source the mark-up stops at the first Perch content tag.

This happens when PHP errors but your hosting configuration is set up to hide the errors.

Things to check:

  1. Did you get a pass from the Compatibility Test for this server?
  2. Are all the Perch files on the server? Check they have uploaded properly. We often see this problem when people have used Dreamweaver to FTP their files. We do not advise ever using the built-in Dreamweaver FTP. It is unreliable.

If you passed the Compatibility Test and are sure all the files are uploaded then we will need to see what is in your PHP Error Log. This is a different log to your web server access log, and you may need to ask your host for the PHP Error log location. Raise a support ticket containing the information from that log so we can help you.

1.4. When I try to login I get the message - Sorry, your license key isn't valid for this domain

When signing into your installation of Perch, you may see the following error:

Sorry, your license key isn't valid for this domain.

This is usually because the domain you have installed Perch at does not match the live or testing domain specified in your account. To fix this:

  1. Log into your account at
  2. Click on the name of your license
  3. Complete the form with Live and Testing domain that match the locations at which you have Perch installed.

1.5. The login page just reloads even though my username and password are correct

If you are trying to log into the Perch admin with a username and password that you know to be correct but the page just reloads at login again, it may be that sessions are not configured properly on your server.

We have some information specific to hosting companies we already know about later in this manual. If your host isn't covered then search their help document for "PHP Sessions" or raise a support ticket with your hosting company and ask if there is anything you need to do to get sessions working.

1.6. New Regions are not showing up in the administration area

If you have created new regions in your page by adding Perch content tags and the regions do not show up in the list in admin under Content, check the following things.

If you have edited your page locally but are checking on the live server, have you uploaded the new page with the regions to your live server? You will not be the first person to be scratching your head wondering why changes haven't appeared for this reason.

After uploading your page did you visit it with your web browser before checking the admin? Perch will not know the new regions are there until you have visited the page at least once.

Check that PHP is running on the pages of your site. If you are using .html rather than .php pages your server probably is not configured to server these as PHP. To check View Source on one of the pages that is not working. If you can see the Perch include or the Perch Content Region tags then PHP is not running. Either rename your pages with a .php file extension or follow the advice in the documentation to create a .htaccess file that will allow parsing of .html as .php:

1.7. Can I rename the Perch folder?

You can rename the Perch folder so that the admin user goes to /admin or something else when logging into Perch. If you've already got Perch installed, rename the folder and then edit your config.php file (in /perch/config/) and change the line that reads:

define('PERCH_LOGINPATH', '/perch');

If you'd renamed your folder to 'admin', you'd change this line to:

define('PERCH_LOGINPATH', '/admin');

And you're done.

If you've not already installed Perch, rename the folder first (e.g. to 'admin'), then go to /admin/setup in your browser and under Install Location, set the folder name to:


2. Templates

2.1. How do I add a WYSIWYG Editor?

Perch enables you to include many commonly used JavaScript WYSIWYG editors.

Read the help documentation on this subject to learn how to implement your editor of choice:

We also have versions of TinyMCE and ckEditor packaged and ready to install. Download these at:

2.2. Why is Perch adding paragraph tags in my content?

The default tenplate for a block of text uses the MarkItUp Editor with Textile set to true. Any content marked up by this editor will be wrapped in a paragraph <p></p> element. Other WYSIWYG editors will do the same thing.

If you just want a single line of text with no mark-up then use the text type in your template and do not add textile="true" or an editor to your template.

3. Images and uploads

3.1. What is the largest filesize Perch can upload?

If you use the template tag for a file in your template this will enable editors to upload a file via the interface that can be downloaded from your website - for example a PDF file. The maximum size of this file is not dictated by Perch, but rather by your hosting company.

To check what your maximum file size will be then look at the Diagnostics Report in the Perch admin under Settings. There wil be a value for PHP max upload size: If you need to upload files larger than this value you will need to contact your hosting company and ask if it can be increased.

3.2. Images fail to upload, or don't appear after upload

If images are failing to upload, or upload but then don't appear on the site it may be that the images are too large or complex for your server to upload or process. The size and complexity of images that can be uploaded to Perch will depend entirely on your hosting configuration.

Check with a very small image and see if that uploads successfully. If so, it may be that the image size is too large for the upload limit defined by your host - see "What is the largest filesize Perch can upload?" for details. If the image size is smaller than the max upload size set by your host then it could be that the image is very complex and so the memory limit on your host is to low to process such images. This tends to happen with very large, complex images and you need a server that has been configured to cope with such images if this is a requirement for you. As a rule of thumb, the cheaper the hosting the lower the memory limit as they will have many sites sharing the resources.

If you have to use hosting with low limits then you will need to upload smaller images. You could direct your clients to a photo editing site such as Pixlr if the images they have are very large and get them to save a smaller version ready for upload.

4. HTML and CSS

4.1. Why are there no spaces between my paragraphs?

If the output from Perch doesn't look like you expected, the first thing to do is View Source in your browser and see what HTML is being generated.

If the HTML looks ok, then the problem most likely lies with your CSS. It's easy to forget that something like this:

* {margin: 0; padding: 0;}

will remove the spaces between paragraphs and the indentation on lists. To put the spacing back:

p { margin-bottom: 1em; }
ol, ul { margin-left: 2em; }

4.2. Perch is displaying characters with accents and umlauts incorrectly

Perch uses UTF8 throughout so charcters with accents will be stored correctly, however you need to make sure that you pages are also UTF8 by setting the correct meta tag:

For HTML4:

<meta http-equiv="Content-Type" content="text/html; charset=utf-8">


<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />


<meta charset="utf-8" />

5. Email and forms

5.1. I am not getting password reset emails

If you request a new password from Perch and the email does not show up then the most likely reason is that PHP mail() is not configured correctly. If you are working locally (on your own computer) using something like MAMP or XAMP then check with the provider of that software how to configure mail.

If your site is live on your hosting then raise a ticket with your host and ask them if there is anything you need to do to get PHP mail() working. If you don't understand the answer then raise a ticket with us and paste in exactly what you have been told by your host.

If mail is being sent but you are not receiving it then it may be that the email is being caught by a spam filter. So check any junk or spam mailboxes that you have for your account.


1. How to report a problem

We're here to help if you have a problem or a question when using Perch, but there's some simple things you can do to help us help you.

Search the Knowledge Base

You're here already, so use the search box and see if anyone else has previously had the problem you're experiencing. You might find your answer without even needing to ask.

Is this a question or a problem with Perch?

If you have a question - for example you want to know how to do something, or even if it is possible to do something - then raise your question in the Forum. Official Perch support work in the forums as well as answering tickets, however our community are also really helpful and you may find that someone out there has already solved your problem. By posting to the forum you help everyone as if you have a question it is likely that someone else does too.

If you have an error mesage, can't get Perch to install on your hosting or think you have found a bug then please raise a private support ticket.

Grab your Diagnostics Report

If the problem is of a technical nature (like something not working), it will really help us to see the Diagnostics Report from your installation of Perch. To get the report, log in as a admin user (such as your main account) and go to Settings. There's a Diagnostics Report link in the sidebar. The report doesn't contain your passwords or confidential information, just the technical information about the server and your Perch configuration.

Provide as much information as possible

To help you out as quickly as possible, there's some basic information that we need. We need to know what the problem is, how the problem occurred (step by step, to help us reproduce it), and critically what you expected to happen. We've written about this in more detail on our company blog - you may wish to read Reporting Bugs - a How-to Guide for more tips.

Hosting specific issues

1. NetFirms

NetFirms are one of the hosts who do not have sessions fully configured. You can find information on how to configure PHP on NetFirms here: you need to set your sessions.save_path as described in that document.

2. PowWeb

PowWeb are one of the hosts who do not have sessions fully configured. You can find information on how to configure PHP onPowWeb here: you need to set your sessions.save_path as described in that document.

3. FatCow

FatCow requires that you add your session path to Perch as explained in the instructions on the FatCow website.

Once you have your FatCow home directory path, you need to add it to perch/config/config.php (at the top inside the PHP tags) and if you need to run the setup on your server also to the top of perch/setup/index.php