When an image is shown on a Dynamicweb website — a product photo, a banner, a thumbnail — it is usually served through the built-in image handler (GetImage.ashx). Instead of sending the original file, the image handler can resize, crop, and convert the image on the fly, so a 4000-pixel photo from the Media library can be delivered as a small, fast-loading thumbnail without anyone having to prepare it manually.
The settings under Settings > System > Web & HTTP > Image handler control how that process behaves:
- How long browsers are allowed to cache the images they download
- How much images are compressed when converted to the WebP format
- What happens when a requested image is missing
- Which underlying components — providers — carry out the actual image and PDF processing
In most cases the defaults work well, and you only need to visit this page to fine-tune performance or troubleshoot missing images.
Settings
| Setting | Setting path | Default |
|---|---|---|
| Send 404 header with alternative image | /Globalsettings/Settings/ImageHandler/Send404IfMissingImage |
Off |
| Cache-control max-age in seconds | /Globalsettings/Settings/ImageHandler/CacheSeconds |
604800 (7 days) |
| Default webp quality | /Globalsettings/Settings/ImageHandler/DefaultWebPQuality |
65 |
Send 404 header with alternative image
When a template requests an image through the image handler, it can specify an alternative image — a fallback shown to visitors if the original file is missing, for example a generic "image coming soon" placeholder for products without photos.
Normally, the fallback image is delivered with a 200 OK status, which tells browsers, search engines, and monitoring tools that everything is fine. That can be misleading: search engines may index placeholder images, and broken-image reports stay empty even though real images are missing.
With this setting enabled, visitors still see the fallback image, but the response carries an HTTP 404 Not Found status — signaling that the original image is missing. This makes missing images visible to SEO crawlers and monitoring tools without degrading the visitor experience. To help troubleshooting, the response also includes an X-404-status-by: dw-getimage-using-alt-image header, so you can tell these responses apart from ordinary 404s.
Note
If an image is missing and no alternative image was specified in the request, the image handler always responds with a plain 404 — regardless of this setting.
Cache-control max-age in seconds
When a browser downloads an image, it keeps a local copy so it doesn't have to download the same file again on the next page view. This setting controls how long — in seconds — browsers (and CDNs) are allowed to reuse that copy before checking back with the server. Technically, it sets the Cache-Control: public, max-age=... header on all responses from the image handler.
The default is 604800 seconds (7 days), which suits most websites. Setting the value to 0 or below simply falls back to the default.
- A higher value means faster repeat visits and less load on the server — but if you replace an image file without changing its name, returning visitors may see the old version until their cached copy expires.
- A lower value makes image changes show up faster for returning visitors, at the cost of more requests to the server.
Tip
Even after the cache period expires, browsers don't necessarily re-download the image. The image handler tags every image with a fingerprint (an ETag), and if the image hasn't changed, the server simply replies "not modified" — a tiny response instead of the full file.
Caching is also the reason why an image replaced under the same file name doesn't show up immediately for returning visitors. Understanding image and browser caches explains this in depth, including how to publish image changes so every visitor sees them right away.
Default webp quality
WebP is a modern image format that produces significantly smaller files than JPEG or PNG at comparable visual quality — smaller files mean faster pages. When templates ask the image handler to deliver images as WebP, this setting decides how much the images are compressed, unless the individual image URL specifies its own quality.
The value is a number up to 100:
| Value | Meaning |
|---|---|
100 |
Highest quality, largest files |
65 (default) |
Good balance between visual quality and file size for most photos |
| Lower values | Smaller, faster files with increasingly visible compression artifacts |
-1 |
Lossless compression — pixel-perfect but produces much larger files |
Note
Large image files make pages slower to load, which affects both visitor experience and search rankings. Only raise this value if you have a concrete visual quality problem. And don't worry about browser support — if a visitor's browser can't display WebP, the image handler automatically delivers JPEG instead.
Image providers
The actual image work — reading dimensions, converting formats, rendering PDFs, and so on — is carried out by pluggable components called providers. Dynamicweb ships with a default provider for each task, and when a dropdown is set to Use default, that built-in provider is used.
You only need to change these if a developer has installed a custom or third-party provider on the solution — for example, an alternative image-processing library or a different PDF engine. Custom providers appear automatically in the relevant dropdown once installed.
| Provider | What it does |
|---|---|
| Converter provider | Resizes, crops, and converts images between formats (JPEG, PNG, WebP, …) when they are requested through the image handler. This is the workhorse behind on-the-fly image scaling. |
| Size provider | Reads the pixel dimensions (width and height) of image files. |
| Attributes provider | Reads basic image information such as dimensions, color depth, and resolution. |
| Metadata provider | Reads metadata embedded in image files — for example EXIF and IPTC tags such as camera information, copyright, and keywords. |
| Editor provider | Applies image edits such as converting to grayscale, black & white, or negative. |
| Pdf converter provider | Turns PDF pages into images — used for example to generate preview thumbnails of PDF files. |
| Pdf renderer provider | Generates PDF documents from content — used by features that produce PDFs. |
Note
If a selected provider can't be loaded — for example because the add-in was removed from the solution — Dynamicweb quietly falls back to the first available implementation, so image processing keeps working.
Related articles
- Understanding image and browser caches — why a replaced image may not update immediately for returning visitors, and how to publish image changes reliably.
- Image Handler for implementers — the full GetImage parameter reference and how to use the image handler from Razor templates, including responsive images.
- Security settings — the Image validation section restricts which image parameter values (width, height, format, quality, …) the image handler accepts, to prevent abuse.