AEM Dispatcher

Understand the AEM Dispatcher — the caching and security layer that sits in front of your publish instance. Learn how it works, how to configure it, and why it breaks in production.

Last reviewed: December 2024

·AEM 6.xAEM as a Cloud Service
✅
Quick Understanding: The Dispatcher is a caching reverse proxy that sits between your users and the AEM Publish server. It caches rendered HTML pages so AEM doesn't have to render the same page thousands of times. It also acts as a security filter, blocking direct access to AEM.

🔍 What Is It?

The Dispatcher is an Apache HTTP Server module (mod_dispatcher) that Adobe provides. It does two main jobs:

1. Caching

When a user requests a page, the Dispatcher checks if it has a cached version. If yes, it serves the cached HTML directly — AEM never gets involved. This makes your website extremely fast.

2. Load Balancing & Security

The Dispatcher acts as a reverse proxy in front of one or more AEM Publish instances. It:

  • →Blocks access to sensitive AEM URLs (like /system/console, /crx/de)
  • →Distributes load across multiple publish instances
  • →Provides a security layer between the internet and AEM

Without the Dispatcher, every page request would hit AEM directly — which would be slow and expose your AEM instance to the internet.

🎯 Why Do We Need It?

Performance: AEM rendering is expensive. A complex page might take 200–500ms to render. With Dispatcher caching, the same page is served in under 10ms from the filesystem.

Scalability: Without caching, a traffic spike would bring AEM down. With Dispatcher, most requests never reach AEM.

Security: AEM's author and publish instances should never be directly accessible from the internet. Dispatcher acts as the gatekeeper.

High Availability: Dispatcher can route around a failed publish instance, keeping the site up.

🏗️ What Happens in Real Projects?

In a real project, the Dispatcher setup looks like this:

Author Flow:

Author → Author Instance (no Dispatcher)

Publish Flow:

User → CDN → Dispatcher → AEM Publish

Typical Dispatcher configuration tasks:

  • →Configure which pages to cache (usually everything except /bin, /libs, /apps paths)
  • →Configure cache invalidation (flush rules)
  • →Set up vanity URL rewrites
  • →Block sensitive URLs (/system/console, /crx/de, /bin/querybuilder)
  • →Configure sticky sessions for personalized content
  • →Set up HTTP headers (Cache-Control, X-Frame-Options)

Cache Invalidation:

When an author publishes a page, AEM sends a flush request to the Dispatcher, which deletes the cached version. Next request regenerates the cache.

⚙️ How It Works

Request Flow:

  1. User requests /en/home.html
  2. Dispatcher checks its cache folder (usually /var/cache/dispatcher)
  3. If cache exists → serve cached file directly (fast!)
  4. If no cache → forward request to AEM Publish
  5. AEM renders the page, returns HTML
  6. Dispatcher caches the HTML to disk
  7. Dispatcher returns HTML to user

Cache Invalidation Flow:

  1. Author publishes a page in AEM Author
  2. AEM Author replicates content to AEM Publish
  3. AEM Publish sends a flush request to Dispatcher
  4. Dispatcher deletes the cached file for that page
  5. Next request regenerates the cache

Key Configuration Files:

  • →dispatcher.any — Main configuration file
  • →filters.any — URL allow/block rules
  • →cache.any — What to cache and for how long
  • →virtualhosts.any — Domain mapping
  • →renders.any — AEM Publish instance addresses

Cache Storage:

Dispatcher stores cache as actual files on disk, mirroring the URL structure. /en/home.html is stored as a file at /var/cache/dispatcher/en/home.html.

AEM Dispatcher Architecture — Request Flow

👤

User Browser

HTTP Request

request
cache hit ↩
🌐

CDN

Edge Cache

request
cache hit ↩
🛡️

Dispatcher

Cache + Filter

request
cache hit ↩
⚡

AEM Publish

Render Engine

Cache Miss → Request passes through all layers
Cache Hit → Response returned from nearest cache

💻 Example

Dispatcher Configuration Examples — Key sections of dispatcher.any configuration with explanations.

apache
/filter {
    # Block everything by default
    /0001 { /type "deny" /url "*" }

    # Allow public pages
    /0010 { /type "allow" /url "/content/mysite/*" }
    /0011 { /type "allow" /url "/libs/granite/csrf/token.json" }

    # Allow static assets
    /0020 { /type "allow" /url "/etc.clientlibs/*" }
    /0021 { /type "allow" /url "/content/dam/*" }

    # Block sensitive paths (always include these!)
    /0100 { /type "deny" /url "/admin*" }
    /0101 { /type "deny" /url "/system/console*" }
    /0102 { /type "deny" /url "/crx/*" }
    /0103 { /type "deny" /url "/bin/querybuilder*" }
    /0104 { /type "deny" /url "*.infinity.json" }
    /0105 { /type "deny" /url "*.tidy.json" }

    # Allow specific API endpoints
    /0200 { /type "allow" /url "/bin/myproject/api*" }
}

🤔 Common Confusions

❓ Why does my published content not show up immediately?

The Dispatcher served the old cached version. After publishing, AEM sends a flush request to invalidate the cache. If the flush didn't work, check: 1) Dispatcher flush agent configuration in Author replication agents, 2) Network connectivity between Publish and Dispatcher, 3) The flush agent's log in AEM.

❓ What is the difference between Dispatcher flush and cache invalidation?

They're the same thing. "Flush" is the AEM term for sending the invalidation request. "Cache invalidation" is what the Dispatcher does when it receives that request — it deletes the cached file so the next request regenerates it.

❓ Can the Dispatcher cache personalized content?

No. Personalized content (content that varies per user) should not be cached by Dispatcher. Use client-side personalization (JavaScript + APIs) or configure the Dispatcher to not cache URLs that contain personalized content.

❓ What is a "statfile" and why does it matter?

A statfile is a file the Dispatcher uses to track when the cache was last invalidated. When AEM flushes a page, the Dispatcher updates the statfile. All cached files older than the statfile are considered stale. The statfile level determines how broadly the cache is invalidated.

🚨 Common Production Issues

Published content not appearing

flush agent not configured, or Dispatcher can't reach the flush endpoint. Check replication agent logs.

Entire site cache wiped on every publish

statfile level set too high, invalidating too many pages. Tune /statfileslevel in cache config.

Personalized content showing wrong data

personalized pages are being cached. Add /nocache selectors or configure rules to not cache those URLs.

403 errors on valid URLs

Dispatcher filter rules are too strict. Check filters.any and ensure the URL pattern is allowed.

Dispatcher serving stale content after deployment

old cached files remain. Run a full cache flush after every deployment.

Session-based content cached

requests with Set-Cookie headers should not be cached. Configure /ignoreUrlParams and cookie handling.

AEM Cloud Service invalidation misses pages

vhost configuration does not match localhost or Adobe cloud host aliases used by invalidation requests.

Marketing campaign URLs create duplicate cache files

tracking query parameters are not ignored consistently in /ignoreUrlParams.

Persisted GraphQL queries return 403

Dispatcher filters do not allow the /graphql/execute.json path for the intended site configuration.

✅ Best Practices

Always deny everything by default in filters.any and explicitly allow only what's needed.

Never allow /crx/de, /system/console, or /bin/querybuilder through the Dispatcher.

Set appropriate Cache-Control headers in AEM to control browser caching in addition to Dispatcher caching.

Use /statfileslevel to control cache invalidation granularity

level 2 or 3 is usually appropriate.

Test Dispatcher configuration locally using the Dispatcher SDK before deploying.

Monitor cache hit ratio

a healthy Dispatcher should have 90%+ cache hit rate.

Use URL fingerprinting for client libraries so they can be cached indefinitely.

Treat Dispatcher filters as application security controls and review them with every new servlet, GraphQL endpoint, or DAM delivery pattern.

Define query-parameter policy explicitly

deny by default, allow functional parameters, and ignore common marketing parameters for cache efficiency.

For AEM as a Cloud Service, test vhosts, filters, rewrites, and cache rules with the Dispatcher SDK before Cloud Manager deployment.

🏛️ Architect's Note

Senior Architect's Perspective

The Dispatcher is often the most misunderstood part of AEM architecture. Here are the things architects need to get right:

Cache Strategy: Design your URL structure with caching in mind. Personalized URLs, session-based content, and dynamic data should never be cached at the Dispatcher level. Use client-side rendering for personalization.

Security Hardening: The Dispatcher's filter rules are your first line of defense. Work with your security team to review filters.any before go-live. Adobe publishes a security checklist — use it.

AEM as a Cloud Service: In AEMaaCS, the Dispatcher configuration is managed through the Cloud Manager pipeline. The Dispatcher SDK allows local testing. The CDN layer (Fastly) sits in front of the Dispatcher, adding another caching layer.

Performance Tip: For high-traffic sites, consider a two-tier cache: CDN (Fastly/Akamai) → Dispatcher → AEM Publish. Most traffic should never reach AEM.

💬 Frequently Asked Questions

How do I test Dispatcher configuration locally?

Adobe provides the Dispatcher SDK (for AEMaaCS) and Docker-based Dispatcher tools. For AEM 6.5, you can use the Dispatcher Converter tool. Always test filter rules with curl commands before deploying to production.

What is the difference between Dispatcher caching and CDN caching?

Dispatcher cache is stored on the Dispatcher server's filesystem — it's close to AEM and handles cache invalidation from AEM. CDN cache is distributed globally — it's closer to users but harder to invalidate quickly. Use both: CDN for global performance, Dispatcher for origin protection.

Can I have multiple Dispatcher instances?

Yes. Large sites often have multiple Dispatcher instances behind a load balancer, each with its own cache. Cache invalidation must be sent to all Dispatcher instances when content is published.

How does the Dispatcher handle HTTPS?

The Dispatcher itself handles HTTP. SSL termination is done at the Apache/load balancer level before the Dispatcher module. Configure your SSL certificates in the Apache VirtualHost, not in the Dispatcher configuration.

What happens to the Dispatcher cache during an AEM upgrade?

The Dispatcher cache remains intact during AEM upgrades. However, if your component output changes after an upgrade, you should flush the entire cache after the upgrade is complete to ensure users see the new rendered output.

🎯 Key Takeaways

1Dispatcher = caching reverse proxy + security filter in front of AEM Publish
2Cache is stored as files on disk — fast to serve, easy to flush
3Flush = delete cached file → next request regenerates it
4Filter rules are your security layer — deny everything, allow explicitly
5Never cache personalized, session-based, or user-specific content
6Monitor cache hit ratio — 90%+ is healthy for a well-configured Dispatcher

🎯 Practice this topic in interviews

↗ Where this topic fits

Sources

Sources / References

Use these AEM references to verify the concept in official docs and continue into the most relevant SplashRide pages.

Related SplashRide pages

SplashRide AEM learning path

Browse the full AEM topic collection and learning order on SplashRide.

AEM Interview Prep

Practice AEM interview questions and scenario-based answers.

AEM Developer Career Path

This AEM developer career path explains how to become an AEM developer through JCR, Sling, HTL, client libraries, Dispatcher, Cloud Service delivery, project depth, and interview-ready enterprise implementation skills.

Drupal Developer Career Path

A practical route through Drupal content modeling, site building, theming, modules, configuration management, APIs, performance, deployment discipline, and interview preparation.

AEM Architecture

Understand the full AEM architecture - Author, Publish, Dispatcher, and how they work together in enterprise deployments.

AEM as a Cloud Service

Understand what AEM as a Cloud Service is, how it differs from AEM 6.5, and what you need to know to develop and deploy on the cloud platform.