Troubleshooting imagecache

The imagecache module is able to serve different versions of uploaded images. It does this in an ingenious way, making it hard to diagnose once something goes wrong. The following may help you.

How does imagecache work?

Imagecache URL's

In the Drupal menu system imagecache can be found at the URL "/<file system path>/imagecache". Supposing you instructed imagecache to create a "small" version of an image, the corresponding imagecache URL will look like this:

http://www.example.com/files/imagecache/small/files/pictures/img001.jpg

This is composed of four parts:

• files - your Drupal files directory e.g. 'files' or 'sites/default/files'
• imagecache - the module name
• small - the imagecache version ("preset") name
• pictures/img001.jpg - the path of the originally uploaded file

The trick

Drupal's .htaccess file contains rewrite rules. Basically these rules say:

1. Try to find whether a file matching the exact URL exists. If so, serve the file directly.
2. If not, start Drupal and feed it the URL path.

If http://www.example.com/files/imagecache/small/files/pictures/img001.jpg is requested for the first time the file does not yet exist. So option 2 is chosen: Drupal is started and given the path /files/imagecache/small/files/pictures/img001.jpg. Drupal in turn starts imagecache and gives it the path /small/files/pictures/img001.jpg. This directs imagecache to create a "small" version of /files/pictures/img001.jpg.

At that moment imagecache does two things:

1. It serves the small image back to the user
2. It copies the file to /files/imagecache/small/files/pictures/img001.jpg (if necessary creating subdirectories along the way).

You can guess what will happen the next time the file is requested: option 1 is chosen, the file is served directly. Now you know where the name imagecache comes from.

What can go wrong?

No images in the imagecache directory

First, don't jump the gun and think there is something wrong. Imagecache only creates its images on demand. This means that when you create an imagecache profile, the imagecache directory {}/files/imagecache/{profilename}/ starts off empty.
Only once you've requested a few files using the imagecache URL (or add-on utilities) will the images be created one-by one. The directory will be entirely flushed whenever you modify the preset. Keep this in mind if watching the file folder when debugging.

If you are monitoring that folder remotely via FTP or a web interface, you will frequently need to refresh that view.

Files directory

Go to Administer > Site configuration > File system. Are the file system path and temporary directory writable by Drupal? Is the download method public?

Rewrite

Obviously rewriting needs to work. And clean URL's. Does rewriting work in your files directory? Is .htaccess allowed?

Try this:

1. Upload a file. After that http://www.example.com/files/file.jpg should return the file. And http://www.example.com/files/nonexistantfile.jpg should present a Drupal "page not found" error.
2. If you get an error from Apache instead of Drupal, rewriting is not working. Check (with your host) whether .htaccess is allowed.
3. If not then this part from the Drupal .htaccess file should be copied to the Apache configuration file:
   
   RewriteEngine on
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php?q=$1 [L,QSA]
4. If .htaccess is allowed make sure the original Drupal .htaccess file, including the exact lines above, exists in the main Drupal directory. And secondly make sure the .htaccess file under your files directory contains exactly these two lines (no more no less):
   
   SetHandler Drupal_Security_Do_Not_Remove_See_SA_2006_006
Options +FollowSymlinks
   
   Note for sites upgraded from Drupal 4.7: Older versions of Drupal wrote an extra line to the .htaccess file disabling mod_rewrite which is no longer necessary but will interfere with ImageCache.

   Of course both files should be readable by Apache.

5. If it still doesn't work, and you are using Drupal in a subdirectory, uncomment and modify the RewriteBase.
   
   RewriteBase /<your subdirectory here>

Spaces in filenames

Spaces or other strange characters may prohibit the rewriting process to work correctly. Try uploading images both with and without spaces in their filenames to see if there is a difference.

If this turns out to be the problem:

1. Download and install the transliteration module
2. Enable the transliteration module (which will fix future upload problems)
3. Replace the original theme_imagecache function by this one:
   <?php
function theme_imagecache($namespace, $path, $alt = '', $title = '', $attributes = NULL) {
  $attributes = drupal_attributes($attributes);
  if (module_exists('transliteration'))
  $imagecache_path = file_create_url(file_directory_path() .'/imagecache/'. $namespace .'/'. transliteration_get($path));
  else
  $imagecache_path = file_create_url(file_directory_path() .'/imagecache/'. $namespace .'/'. $path);
  return '<img src="'. $imagecache_path .'" alt="'. check_plain($alt) .'" title="'. check_plain($title) .'" '. $attributes .' />';
}
?>
   
   This will use the transliteration module to encode the filename

4. Flush your imagecache preset

Memory

To manipulate an image it is first decompressed in memory. Therefore file size (in MB) does not matter. What matters are image dimensions (in pixels) and color depth. If you find out large images do not get processed, and smaller images do, the available memory is too small. Either constrain the dimensions of uploaded images or increase the PHP memory limit.

Image toolkit

Imagecache depends on an image toolkit (see Administer > Site configuration > Image toolkit on 5.x, or Administer > Site Configuration > ImageAPI on 6.x) to manipulate images. PHP's built-in GD2 toolkit only handles GIF, JPEG and PNG. BMP files are not manipulated at all, and served to the user in their original size.

If you need e.g. BMP support you could try the imagemagick toolkit.

If you want to block certain file types: Imagefield 5.x-2.0 and up allows you to specify permitted upload file extensions.

PHP Settings

PHP "Safe mode" is not recommended and may interfere with the workings of the image processing libraries. Turn it off if you can.

zend.ze1_compatibility_mode should be turned off.