All posts
Liferay · 13 min read · Sep 21, 2026

Inside Liferay's Caching Layers

Liferay multi-level caching architecture

Almost every 'I changed something but the portal still shows the old value' problem in Liferay is a caching problem. Liferay caches aggressively at multiple independent layers, each with its own lifetime and its own invalidation rules. When data looks stale, the real question is never 'is caching on' - it always is - but 'which layer is holding the old value.' Answering that quickly requires a map of the layers.

The caching stack, top to bottom

Think of caching as a stack. A request may be answered by any layer before it reaches the database, and each layer can independently be stale.

LayerCachesTypical staleness cause
Fragment / portlet cacheRendered HTML outputContent changed but output cached
Entity cacheIndividual model objects by primary keyDirect DB write bypassing the service layer
Finder cacheQuery results (lists of IDs)New record not reflected in a cached query
Hibernate cacheORM-level objectsSecond-level cache not invalidated
Database cacheQuery and buffer poolsOutside Liferay's control

Entity cache: objects by primary key

The entity cache stores individual model objects keyed by their primary key. When you fetch a blog entry by ID, Liferay checks this cache first. It is invalidated automatically when you update the entry through the service layer. The word automatically is doing a lot of work: if you write to the database directly with SQL, bypassing the service layer, the entity cache never learns about the change and happily serves the old object.

Finder cache: results of queries

The finder cache stores the results of finder methods - the lists of IDs returned by queries like 'all entries in this group'. This is separate from the entity cache. You can have a perfectly fresh entity cache and still get a stale list because the finder cache remembers the old set of matching IDs. Adding a record through a direct SQL insert is the classic way to leave the finder cache stale.

java
// Goes through the service layer:
// entity + finder caches are invalidated correctly.
_blogsEntryLocalService.updateEntry(entry);

// Direct SQL insert/update:
// caches are NOT invalidated -> stale reads.
jdbcTemplate.update(
    "INSERT INTO BlogsEntry (...) VALUES (...)");
Bypassing the service layer is the most common source of cache staleness.

Rendered output cache

Above the data layers sits caching of rendered markup - portlet output and fragment output. This can make a page appear stale even when every data cache is correct, because the HTML was rendered and stored before the data changed. Personalized or permission-filtered output complicates this: caching one user's rendered view and showing it to another is a subtle correctness bug, not just a freshness one.

Clustering multiplies the problem

In a clustered deployment each node has its own caches. Invalidating a cache on one node does not automatically clear it on the others unless cache replication or invalidation messaging is configured. A record can look updated on the node you are hitting and stale on the node your colleague is hitting. This is why 'it works for me' is a legitimate and important clue in a clustered Liferay environment.

A debugging order that works

  1. Reproduce with a hard refresh to rule out the browser cache first.
  2. Check whether the change was made through the service layer or via direct SQL.
  3. If the object is stale, suspect the entity cache; if a list is stale, suspect the finder cache.
  4. If the data is right but the page is wrong, suspect the rendered output cache.
  5. In a cluster, check whether the correct value appears on some nodes but not others.

Conclusion

Liferay's caching is not one cache but a layered stack: rendered output, entities, finders, ORM, and the database beneath. Each layer speeds the portal up and each can independently hold a stale value. The engineers who resolve caching issues in minutes are the ones who know the layers, know that the service layer keeps them coherent, and know that bypassing it is what breaks them. Map the layers once and you stop guessing forever.

Contact

Let’s connect

Have a Liferay or Backend project you’d like to talk through? Fill in the form and I’ll get back to you.

Book Calendar