Last updated May 2, 2011. Created on February 21, 2008.
Edited by HongPong, dman, Elijah Lynn, drewish. Log in to edit this page.

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:

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 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?


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 should return the file. And 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));
      $imagecache_path = file_create_url(file_directory_path() .'/imagecache/'. $namespace .'/'. $path);
      return 'Only local images are allowed.';

    This will use the transliteration module to encode the filename

  4. Flush your imagecache preset


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.

Looking for support? Visit the forums, or join #drupal-support in IRC.


sappling’s picture

While obvious in retrospect, I ran into problems with permissions that might be useful to mention in this helpful guide.

After installing imagecache, I went to the permissions page and assigned the appropriate imagecache permissions to my different roles. What I didn't realize, was that when I later added my first imagecache preset, a new permission just for viewing that preset was created. I had not gone back and given that permission to any role, so it seemed to me that imagecache was mysteriously not working. After updating the permissions, everything works fine.

livan1980’s picture

I spend 3 days trying to see why the module doesn't work properly, and as soon I change the permissions, it work perfectly.

texas-bronius’s picture

The .htaccess in sites/default/files was the problem for me for a very old site that had been upgraded from previous versions of core where .htaccess had RewriteEngine Off.

- no image after Save Preset (yes, a GIGANTIC drupal icon should show even without any actions added)
- clicking on the imagecache preset preview url shows your site's home page (instead of a 404 or your imagecache preset preview image)

As suggested in #177934: imagecache and .htaccess in files directory, delete the remnant, offending .htaccess in sites/default/files, visit admin/settings/file-system, and Drupal will rebuild your .htaccess for you

80s themed Drupal T-Shirts

wanderingstan’s picture

I was also having trouble with imagecache not working on my production server. In my case, the solution was to take all of the preset directories out of source control (svn) and just let imagecache create them automatically on-the-fly. E.g. I left sites/default/files/imagecache directory in svn (and given correct permissions for apache to read/write), but took out subdirectories.

wanderingstan’s picture

Another imagecache gotcha:

You may also need to rebuild your menu cache. You must do this if you have multiple sites, and are restoring a database from another site. In my case, drupal had cached lots of imagecache-related paths containing my development URL. (Discovered this my searching through the database backup that I was restoring to the production server.)

DigitalFrontiersMedia’s picture

wanderingstan -- you are a rockstar! Thanks! I was stymied by this little detail for hours!

Phone: 941.677.DFM1 ( 941.677.3361 )
Skype: DigitalFrontiersMedia
Twitter: DigitalFrontier

Andrew Jamieson’s picture

This worked for me. thanks!

Paintbox’s picture

Adding to the mix and good to know, when in off-line mode, imagecache refused to work here. Checked all of the above first.

fyberoptik’s picture

For those drupaling with with nginx, some great config here:

I had a long standing bug with imagecache not generating files. After checking over config I finally found this line in my config, I hadn't enabled the location for D6.

# This is for D6
        location ~ ^/sites/.*/files/imagecache/ {
        # This is for D7 and D8
        #location ~ ^/sites/.*/files/styles/ {
                try_files $uri @rewrite;

Hope this helps someone!