Documentation

Override AEM “AdaptiveImageServletMappingConfigurationFactory” for WebP support

Last update: Tue Dec 30 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

Adobe Experience Manager (AEM)’s Image Component doesn’t render WebP assets unless the AdaptiveImageServletMappingConfigurationFactory configuration includes the WebP extension. Deploying a custom configuration using default naming and location fails because AEM continues to apply its out-of-the-box (OOTB) settings. To resolve the issue, rename the configuration file, place it in the correct folder, and redeploy your package.

Description description

Environment

Adobe Experience Manager (AEM) Managed Services, v6.5 - Sites

Issue/Symptoms

  • The AEM Image Component doesn’t render WebP images on pages.
  • A custom configuration meant to add WebP support gets ignored after deployment.
  • The system keeps applying the default AdaptiveImageServletMappingConfigurationFactory settings instead of the custom configuration.
  • The WebP image assets stay unavailable even after deploying the updated configuration file.

Resolution resolution

Follow these steps to address the issue:

  1. Navigate to Tools > Operations > Web Console > system/console/configMgr on the AEM 6.5 AMS author instance…
  2. Search for AdaptiveImageServletMappingConfigurationFactory, then open and copy the configuration for com.adobe.cq.wcm.core.components.internal.servlets.AdaptiveImageServletMappingConfigurationFactory coreimg.
  3. Create or rename the code-based configuration file as com.adobe.cq.wcm.core.components.internal.servlets.AdaptiveImageServletMappingConfigurationFactory coreimg.cfg.json.
  4. In this file, include webp in the file extensions property, for example: "fileExtensions": [ "jpeg", "jpg", "png", "gif", "webp"].
  5. Place this file under the author run mode folder in your codebase, for example: .../apps/<project>/config.author/ (and similarly config.publish/ if needed for publish).
  6. Redeploy the code package.
  7. After deployment, verify in /system/console/configMgr that com.adobe.cq.wcm.core.components.internal.servlets.AdaptiveImageServletMappingConfigurationFactory coreimg is active, and its file extensions list contains webp.
recommendation-more-help
3d58f420-19b5-47a0-a122-5c9dab55ec7f