DocumentationExperience Cloud KCS

AEM: Inconsistent query parameter ordering affects ETag and caching

Last update: October 9, 2026

This article describes how non-deterministic ordering of query parameters in image URLs generated by the Asset Delivery API or Core Image Component can lead to unstable ETags and inefficient caching in Adobe Experience Manager. It provides steps to resolve the issue.

Description description

Environment

Adobe Experience Manager as a Cloud Service (all versions)

Issue/Symptoms

  • HTML page cache invalidation and inconsistent ETag values are observed on the delivery tier.
  • Some If-None-Match requests return 200 OK instead of 304 Not Modified, resulting in unnecessary downloads and reduced cache efficiency.
  • Image URLs generated by the Asset Delivery API or Core Image Component include query parameters, such as width, quality, and preferwebp, in a non-deterministic order. This causes the literal HTML response body to change between requests, even when the content is functionally identical.

Examples of inconsistent parameter ordering:

  • /adobe/dynamicmedia/deliver/path/to/image?width=1600&quality=85&preferwebp=true
  • /adobe/dynamicmedia/deliver/path/to/image?quality=85&preferwebp=true&width=1600

Cause

Unordered collections, such as HashMap, HashSet, or Collectors.toMap(), used to build query parameters result in non-deterministic ordering. This causes the HTML output to vary between requests and breaks ETag-based caching.

Resolution resolution

Follow these steps to resolve the issue:

  1. Identify the Sling Model or HTL code responsible for generating image URLs in the affected component, for example, the homepage hero or carousel.

  2. Check whether query parameters are assembled using unordered collections such as HashMap, HashSet, or Collectors.toMap().

  3. Refactor the code to ensure deterministic parameter ordering:

    • Use a TreeMap to sort parameters by key, ensuring consistent ordering.
    • If insertion order must be preserved, use a LinkedHashMap and ensure the insertion order is consistent across requests.

  4. Deploy the updated component.

  5. Verify that the generated image URLs have a consistent query parameter order across all Publish instances and requests.

  6. Confirm that ETags for the same page are identical across Publish instances and that CDN/browser caching works as expected, that is, 304 Not Modified responses are returned when appropriate.

recommendation-more-help
experience-cloud-kcs-help-kbarticles