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, "&" and "#" 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: (you probably don't need to use this step anymore, delete?)
   

   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.

Troubleshooting - looking for clues

Imagecache and ImageAPI require that certain image processing libraries exist on your server. You must verify that that's all good. Visit your Administration "status" page in reports and check there are no errors there. Visit the ImageAPI settings page and ensure at least one of the "Image Toolkits" is enabled. This is all in in the README.

Most things that can go wrong in the process will trigger an error of some sort, and that error is logged. Look at your error log in Administration > Reports > Recent log messages. There you may see some 404s relating to your missing images (which means there is a path or rewrite problem), or some other message explaining why the image could not be generated (which often is a result of unavailable libraries).

Try visiting the expected path of the test image to see if you get a visible error message. When previewing an imagecache preset, even if the preview image is broken (which demonstrates there is a problem) there should be a link from the broken image to the page request. Try following that and see what the server is complaining about.

Before commenting here!...

Handbook pages are not a support queue. If you have questions or problems, please post an issue in The Imagecache Issue Queue. If you solve it with help over there, then come back and explain what the problem was and how you fixed it.
Large questions and "Me Too" comments may get deleted from here at any time. We want to help folk with common troubleshooting steps described on this page, to make it easier for everyone.