How to Fix Missing Drupal Image Style Derivatives

If an original image opens but its thumbnail or cropped version returns an error, the file itself may be fine. Drupal image styles create transformed derivatives from source images, and those files depend on the source URI, configured style, file permissions and the web server’s ability to deliver the result.

Editorial illustration tracing a broken Drupal image derivative from source file through style processing to the rendered page

Editorial illustration: trace source, style, generated derivative and delivery separately.

Summary

  • Compare the original file URL with the styled URL to locate where the failure begins.
  • Check the image style, source file URI, public/private scheme and writable files directory before changing code.
  • Regenerate only after correcting the cause, then verify the page and derivative URL.

How Drupal image styles work

An image style applies one or more effects—such as scaling or cropping—to an original image. Drupal stores or generates a derivative for a specific style and source path; a displayed thumbnail is therefore not necessarily the same file as the uploaded original. The Image module documentation describes styles and their generated paths, including files beneath the site’s files directory.

After a migration or deployment, a page can reference a derivative that was never generated on the new environment. A missing file is one possibility. A mismatched file URI, an unavailable style, or a permissions issue can produce a similar symptom, so start by comparing URLs rather than repeatedly clearing caches.

Step 1: compare original and styled URLs

Open the page with the broken image and copy the image URL. Then locate the original file through Drupal’s media/file record or content edit form and open its URL directly. Avoid guessing the original path if the site uses private files or a custom storage backend.

Interpret the result:

  • Original and derivative both fail: inspect the source file record, storage, URI and access configuration first.
  • Original works, derivative fails: focus on the image style, derivative generation, permissions and rewrite handling.
  • Derivative opens directly, page does not: check the rendered markup, responsive image settings, browser console and cache layer.
  • Only private images fail: inspect private file access and the route/access behavior; do not switch private files to public just to make a thumbnail appear.

Record the failing URL and response status if you can. A 403, 404 or 500 points to different layers, though a proxy can change what the browser sees.

Step 2: confirm the style and display configuration

In the administration UI, inspect the relevant image style and its effects. Confirm that the style still exists and that the view mode, formatter, responsive image mapping or custom code is using the expected machine name. A renamed style or stale configuration can leave content pointing at a style that is no longer available.

If the original is displayed correctly in one view mode but not another, compare their formatters and style assignments. Test one representative image and one style before changing every content type. After an import, ensure the active configuration contains the style definition expected by the environment.

Step 3: check URI, scheme and file storage

Compare the file URI recorded by Drupal with the actual file location. Common differences arise when a site moves from one filesystem layout to another, a private/public scheme changes, or a deployment copies the database but omits uploaded files. Confirm that the file exists on the server or remote storage under the expected URI.

Do not fix a URI mismatch by hand-editing a database row. Use the project’s supported migration or file-management workflow so Drupal’s file entities and storage remain consistent. If the site uses object storage or a custom stream wrapper, test access to that backend as well as local paths.

Step 4: verify permissions and server behavior

The web/PHP process must be able to read the source image and, where applicable, create derivative files in the configured directory. Check ownership and permissions against your host’s documented setup. Avoid broad 777 permissions: they mask the underlying ownership problem and weaken the file boundary.

For public files, check whether the expected derivative path is accessible through the web server. For private files, confirm that the private path and Drupal access route are configured as intended. A web server rewrite or reverse proxy rule may also prevent the generated file from being served even when it exists.

Review recent deploy, PHP and web-server logs around a failed derivative request. Image processing can fail because of missing runtime support or a memory limit, but verify the actual error before changing PHP settings or installing extensions.

Step 5: regenerate after fixing the cause

Once the original file, style and storage are correct, request the styled image again or use your project’s approved regeneration process. Drupal can generate derivatives as they are requested in supported configurations; larger sites may choose a controlled pre-generation process to avoid a burst of work during peak traffic.

Do not delete every derivative as the first response. That can cause a wave of regeneration requests and increase load, while leaving the real path or permission error untouched. If you have many affected files, test a small sample, estimate the storage and processing impact, then schedule the broader rebuild.

After regeneration, verify the exact styled URL directly and then reload the page. If the file appears but the page still shows the old failure, purge the relevant Drupal, proxy or CDN cache in the order your deployment uses. Confirm that the returned image dimensions and crop match the style; a 200 response can still serve the wrong asset.

A practical example

Suppose the original public image opens, but /sites/default/files/styles/card/public/field/image/storefront.jpg returns 404 after a database refresh. First confirm the card style exists and that the original file is present at the URI Drupal records. If the database came from production but uploads were not copied to staging, the derivative cannot be created because its source is absent. Copy or synchronize the source through the normal deployment process, request the derivative again, then verify both the direct URL and the card view.

If the source exists and the style is correct but the response is 500, check logs for the actual generation error—such as filesystem write failure or image-processing failure—before adjusting server configuration.

Common mistakes

  • Clearing all caches first. Cache clearing does not recreate a missing source file or fix permissions.
  • Changing private files to public. This can expose files that were intentionally protected.
  • Giving the files directory broad write permissions. Correct ownership and documented permissions instead.
  • Rebuilding every image immediately. Start with a small sample and consider resource load.
  • Assuming a successful HTTP response means the issue is solved. Confirm the correct source, dimensions and page rendering.

Bottom Line

Compare the original and styled URLs, confirm the style and file URI, then check storage and permissions. Regenerate after the cause is fixed and verify both the derivative itself and the page component that uses it. This order separates a missing source from a generation or delivery problem.

My Take

Image bugs often look like cache bugs because clearing the cache changes what the browser requests. I would first ask one simple question: does the original file open? That answer narrows the investigation before you touch file permissions or trigger a large regeneration job.

Sources

Further reading