Skip to content

document ASSETS_TRANSFORM_IMAGE_MAX_OUTPUT_DIMENSION #791

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ComfortablyCoding merged 1 commit into from
Jul 29, 2026
Merged

document ASSETS_TRANSFORM_IMAGE_MAX_OUTPUT_DIMENSION #791

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 17 additions & 9 deletions content/configuration/files.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,24 +153,32 @@ the storage driver(s) being used.

## Assets

| Variable | Description | Default Value |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
| `ASSETS_CACHE_TTL` | How long assets will be cached for in the browser. Sets the `max-age` value of the `Cache-Control` header. | `30d` |
| `ASSETS_CACHE_REVALIDATE` | When enabled, sets `Cache-Control: max-age=0, must-revalidate` to force CDNs to revalidate assets on every request. | `false` |
| `ASSETS_TRANSFORM_MAX_CONCURRENT` | How many file transformations can be done simultaneously. | `25` |
| `ASSETS_TRANSFORM_IMAGE_MAX_DIMENSION` | The max pixel dimensions size (width/height) that is allowed to be transformed. | `6000` |
| `ASSETS_TRANSFORM_TIMEOUT` | Max time spent trying to transform an asset. | `7500ms` |
| `ASSETS_TRANSFORM_MAX_OPERATIONS` | The max number of transform operations that is allowed to be processed (excludes saved presets). | `5` |
| `ASSETS_INVALID_IMAGE_SENSITIVITY_LEVEL` | Level of sensitivity to invalid images. See the [`sharp.failOn`](https://sharp.pixelplumbing.com/api-constructor#parameters) option. | `warning` |
| Variable | Description | Default Value |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
| `ASSETS_CACHE_TTL` | How long assets will be cached for in the browser. Sets the `max-age` value of the `Cache-Control` header. | `30d` |
| `ASSETS_CACHE_REVALIDATE` | When enabled, sets `Cache-Control: max-age=0, must-revalidate` to force CDNs to revalidate assets on every request. | `false` |
| `ASSETS_TRANSFORM_MAX_CONCURRENT` | How many file transformations can be done simultaneously. | `25` |
| `ASSETS_TRANSFORM_IMAGE_MAX_DIMENSION` | The max pixel dimensions size (width/height) that is allowed to be transformed. | `6000` |
| `ASSETS_TRANSFORM_IMAGE_MAX_OUTPUT_DIMENSION` | The max pixel dimensions size (width/height) that a transformation is allowed to output. | `3000` |
| `ASSETS_TRANSFORM_TIMEOUT` | Max time spent trying to transform an asset. | `7500ms` |
| `ASSETS_TRANSFORM_MAX_OPERATIONS` | The max number of transform operations that is allowed to be processed (excludes saved presets). | `5` |
| `ASSETS_INVALID_IMAGE_SENSITIVITY_LEVEL` | Level of sensitivity to invalid images. See the [`sharp.failOn`](https://sharp.pixelplumbing.com/api-constructor#parameters) option. | `warning` |

::callout{icon="material-symbols:info-outline"}

When enabling `ASSETS_CACHE_REVALIDATE`, CDNs will revalidate assets on every request instead of serving them straight from their cache. This means one lightweight round-trip to Directus per request, which has a small performance impact compared to the default `max-age` behavior. On an existing Directus instance, the initial CDN cache must also be cleared before revalidation can take effect, as assets already cached will continue to be served with the previous `max-age` rules until they expire.

::

::callout{icon="i-lucide-triangle-alert" color="warning"}
Image transformations can be heavy on memory usage. If you're using a system with 1GB or less available memory, we recommend lowering the allowed concurrent transformations to prevent you from overflowing your server.

`ASSETS_TRANSFORM_IMAGE_MAX_DIMENSION` limits the size of the source image, while `ASSETS_TRANSFORM_IMAGE_MAX_OUTPUT_DIMENSION` limits the size of the transformed result. A transformation that projects a width or height larger than the output limit is rejected with an [`ILLEGAL_ASSET_TRANSFORMATION`](/guides/connect/errors) error.

The output limit applies at every step of a transformation, not only to the final dimensions. A transformation that scales an image up to 10000px and then back down to 2000px is still rejected, because each step is fully applied before the next one runs.

::

## Imports

| Variable | Description | Default Value |
Expand Down
Loading